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printf ("Hello" ) ? 



// 



print "Hello 



JSR printMsg 



say "Hello" 



writeln( "Hello") 
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Startup-Sequence 

Small Openings Can Yield Big Opportunities 



At the Pall '92 COMDEX m Us Vegas, 

Commodore Business Machines bunched the 
third new Arnica into the U.S. marketplace in, is 
many months The newest Amiga, the A1200, 
appears to be ,1 iros> between (lie other two new 
additions to the Anne,,! line, the A4000 and the 
A600 

I Dte the Amiga 4000. the A1200 us.-- the 
Advanced Graphics Chip Set M well as 
AjTUgaDOS&O U ,th.,pn,eol$699foran A1200 
leiS Hard drive, the Amiga OStt now has ,1 less 
expensive option tor getting into the new AA 
Amiga graphics chips (lor more on the AI200, 
please see the |anuarj Issue ol Amnmg Com- 
pulfng ) 



PCMCIA 
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!■(...! 1.1 1- mi. K m Ihr 40MB hjiJ 
ill"" («bov«l by Inleftiil 
I'ciiphftil. jr»d (hf 2 MB 

cipjniion RAM (or the AdOO 

and At 1110 drill by N*W MrdU 
Corpoulion oll>i morr lh*n 
«)m«lhin« In fill J 'lot 



The Amiga 1200 looks remarkable like an 
updated Amiga 500- or possibly a sttclch ver- 
sion ot the Amiga 600— with an off-white v.i- 
and a inciuoiv board expansion panel ac.ess on 
the underside It also has an additional Similar- 
ity to the Amiga t<oo that has not always been 

well received by the Amiga dev eloper commu- 
nity In lieu of Ihe acccs* slot to the Amiga BUS. 
both the A600 and the Amiga 120U haw adopted 
the PC \K IA standard interface for expansion 
de\ ices 

When tins feature was introduced with the 
Amiga 600, many Amiga dev eloper* were greatly 
upset and with g,K>d reason. They had -pent 
time, money, and other resources to develop 
peripherals based on the standard access slot 
found in some conliguiation in everv Amiga 
sin,.- the original inlroduilton of the Amiga 
UHK'ui 19Hs The slnl has seen some ver. 
inge\paiisionpr<xluet~.e>pv«ialK tor the Amiga 
500 

A500mcnmrv expansions, harddnves.NIM 
emulation, and more have taken advantage of 
the intimate. base>tevd connection tins port 



provide- 1 lowever, the PCMCIA port available 
on the Amiga 600 and the Amiga 1200. was 
CKated tor ,i larger audience 

The PCMCIA standard type 2 slot on the 
A600andAI200 was developed asan expansion 
standard for the PC and laptop community. 
There wasa need to supply one standard that a 
Variety of highly specialized devices could use. 

I he result ol this standard has bevn everything 
from RAM and bubble memory lo complex de- 
vices such as FAX /modems and 40MB hard 
drives In devices IH) larger than a credit card 
I'v making thi> standard a port on the Amiga 

1200 and 600, Commodore has not only opened 
the door to its users for a wide variety ot hard- 
ware capabilities, it has also opened a door to its 
developers to provide a wider audience for their 
products. 

What Is PCMCIA? 

i\ Ml IA is an acronym tor the Personal 
Computer Memory Card International Associa- 
tion, a standards organization with over 300 
member companies PCMCIA has created the 
Standards lor the Personal Computer Card or PC 
Card which isoltcn referred toby the standard's 
own name of PC\IC IA Originally developed 

for the portable market the standards were de- 
signed to provide a high level environment for 
new products Now the PCMCIA standard is 
being used bv desktop computers such as IBM 
and, of course. Commodore. 

The PCMCIA standards cover the physical 
dimensions, electrical Specifications, and the 
software architecture for It" Cards. There are 
three physical size spev m.ations in the PCMCIA 
standards: lypel. lypcll.and I v pc III U'hileall 
three specifications maintain the same 68-pin 
connector and the same length and width di- 
mensions, they do differ in thickness. Type I 
cards are 3.3 mm thick. Type II cards are >0 mm 
thick, and lypc III cards are 105 mm thick 
These variances allow a standard to apply to a 
small 40MB hard drive BS well H a 2MB RAM 
memor\ expansion. 

Under the standard, it is possible to con- 
struct a wide variety of computer peripherals 
and dev It >-• \- other hardware manufacturers 
follow the lead of IBM. Commodore, and a va- 
net\ ot laptop computer makers, there will be a 
larger audience Ol potential customers. I bis 
combination of a variety ol product- to an ex- 
panding audience provides Amiga hardware 
manufacturers vvithpossibi 1 1 lii-s ihev have never 
had before 



learning More 

In later issuc-s ice will follow the work that 
Commodore is doing with the PCMCIA Stan* 
dard as well as keep track of what is being 
created in the PC arena The PCMCIA was 
offering speiial distountson their document a 
tion at COMDEX, go.nl on prepaid orders re- 
ceived before December 31, 1992. For more in- 
formation on the standard itself and any other 
help from the PCMCIA organization, please 
contact 
l\ MCIA 

Il)3ix; last Duane \.i 
Sunnyvale, CA 94086 
telephone 1 408) 720-0107 
I A\ (408J720-94I6 
BBS (408) 720-9388 

Who Needs the Market? 

While 1 am sure there are Amiga develop- 
ers who feel there is little to be gained In at- 
tacking this potential market, it is important lo 
note that new developers are providing prod- 

fbf the Amiga 600 and Amiga 1200 with 
U Mi IA interfaces Ihe latest release was an- 
nounced at COM I )I M'v \ew MediaCorpora- 
tion 

New Media has developed a card with up 
lo4MBof additional RAM through the PC "Ml IA 
r»rt. At $240for the2MB PSRAM card and Ms- 
for the 4MB PSRAM card. New Media could 
find a very profitable market for this much- 
needed expansion. For more information on 
Mew Media and their card, contact Mr Simon 
Harvey. V I' otSales& Marketing. New Media 
Corporation. Irvine Spectrum, 13375 Barranca 
Parkway. Building B. Irvine CA 9271 S 

Opportunity? 

OneinterestingfacetoftheAmigaistli.i! it 
has always remained a trend selter in ideas M^t 
potential markets PCMCIA isa portal by which 
Amiga developers can not only provide prod- 
uct for Ihe Amiga, but the) can look at the 
demands, needs, and spe. ideations of other 
markets. Opportunitv does not always knock; 
sometimes it is accessible through a very small 
opening. 




Don Hicks 
Managing Editor 
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You've never heard ot Comeau Computing Neither had I 

until I uw an adt ertisemenl (or Comeau C+ + in AC's Guide To Vte 
Commodore Ann w According to the press reseasc i received with 
Comeau C++. Comeau Computing wm formed in 1985 as a privately 
held consulting firm specializing "' UNIX and C The company 
develops md sells programming ioob> for a variety of hardware 
platforms Its primary commercial pn»ducis appear to be Comeau C++ 
and a -.hell program named CCsh. Comeau C++ ts available for many 
UNIX systems (including various flavors of UNIX). MS-DOS systems, 
and (or AmigaDOS. The company is a founding and voting member of 
the ANSI C++ Committee 

I M i- a general-purpose programming language based on 
C It was developed in the early 1980's at AT&T's Bell Laboratories and 
became publicly available in 1985. Since then, the language has 
undergone several IW isums The turrent revision is 3.0, which is 
defined m the * erskm of the C* - reference manual published in 
February 1990 This version of the reference manual is the base 
document lor ANSI standardization of the language In March 1992, 
revision 3.0 of C» * became available for the Amiga when Comeau 
Computing began "-hipping an AmigaDOS version of their C++ 
development system called Comeau O • 3.0 With templates 

COMEAU C** 

The heart ot Comeau C + . is a licensed port of cfront ("C 
front-end") from AT&T's Unix System Laboratory (USL). This is the de 
facto standard C*- compiler. It is the central part of USL'sC* + 
Language System. Technically. , tront is a compiler, but most program- 
mers refer to it as a translator since it translates C* * source code intoC 
source code. The generated C source code is then compiled by any 
standard C compiler ("C back-end") to produce native code for a 
■.peciti! machine Because of this Come.ui C« • i- not a stand-alone 
C++ development system. You also need a C compiler and standard C 
link, libraries to create executable C + • programs with Comeau C++. 
Ihe C compilers that ,.\n be used with the AmigaDOS version ot 
Comeau C++ are SAS C and Aztec C. The documentation states that 
Matt Dillon's (" compifef system, DICF. may also work with Comeau 
C++ in the future 

In addition to the t • - compiler, Comeau C++ includes an 
install script, documentation, a C pr eproc ess or, a C++ link library. 
standard C++ Include files, and an AREXX script (or compiling and 



linking C+ + programs. The software i- on two disks and the documen- 
tation is in a standard vinyl three-ring binder. The total cost ot the 
package is 5250.00. Ihe price includes shipping and handling. It also 
includes tree lifetime technical support. 

INSTALLING COMEAU C++ 

Installing Comeau C+* is a snap: you simply put Disk l in 
drive 0, change to the DF0: directory, and type "rx install". The rest is 
automatic. You are prompted once for the name of the directory where 
your C include files are kept, and once to change disks. The entire 
installation process requires less than Five minutes on an Amiga 3000. 
The only part of the installation process that is not completely 
automatic is adding various logical directory assignments to your 
startup file. A file named forS containing logical directory names (or 
the Comeau C++ directories is provided with the system. You can 
copy this file into your startup script. After you finish installing 
Comeau C++, you verify that everything works correctly by compiling 
C and C++ versions o! the famous "Hello, world" program and 
running them. 

The installation process creates a directory named Ccomeau. 
All the components of the system are in this directory It includes 
several sub-directories, two "Hello, world" test programs, and some 
documentation. The sub-directories of Ccomeau are ARexx30, c30, 
include30, and Iib30. Before discussing the contents of these directo- 
ries. I need to describe C+ • classes and objects, and describe how 
objects are created and destroyed in (. I l 

C++ CLASSES. OBJECTS, CONSTRUCTORS, AND DESTRUCTORS 

The following is a C- * class definition 
class String 



char ' 



' t private member 



public: 



String* char *etr ill String constructor 

I 

■ 
strcpyl_ati 

' ■ 'strlenlr.- '\0'j 
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A Look at 
Comeau Computing's C++ 3.0 



by Forest W. Arnold 



-StringO // String destructor 

( 

delete []_str: 

I 

// pointer and reference output operators 
friend ostream&operstor«{ostreami. String') : 
friend o3treairiloperator« (ostrean*. Strings) : 
i; 

This class definition defines a type named "String". Classes 
consist of objects together with the operations thai can be applied to 
the classes' objects. Objects are a class's variables. As defined above. 
String objects consist of a single data element: a pointer to a dynami- 
cally allocated character array. The operations that can be applied to 
String objects are String creation. String destruction, and output of a 
String's value. The procedure StringO is called a constructor, and the 
procedure -StringO is called a destructor. Constructors initialize newly 
created objects, and destructors clean them up before the memory they 
occupy is made available for reuse. The C- • compiler is responsible 
for making sure that a class's constructors are called when its objects 
are created, and making sure that its destructors are called when its 
objects arc destroyed. Objects are created by declaring them, or by 
dynamically allocating them using the C++ operator new(). They are 
destroyed when the scope within which they are declared is exited or 
with the C«» operator deleted. Listing I is a simple but complete C- ♦ 
program that creates two String objects, prints their values using an 
overloaded C»* output operator ( « ). and deletes the dynamically 
created String object. Listing 1 also presents the output produced bv 
this program You will notice from the program's output that both the 
String constructor and destructor are called for each object, mn 
though one is created by declaring it outside any procedure (making 
its scope "global") and it is nmi explicitly destroyed. I will explain 
below how theC** compiler makes sure constructors and destructors 
for statically allocated global objects are called. 

COMPONENTS OF COMEAU C+* 

I mentioned above that all the software for Comeau C** is 
contained in several sub-dircctones of a directory named Ccomeau 
The following paragraphs describe the contents of each of these sub- 
directories 



The ARexx30 directory contains only a single file, como r.-.v 
This is an ARexx script that create- an executable program from a C+* 
source code file. After you create the source code file lor vour C*» 
program, you compile and link it using como.rexx. The command to 
compile and link the String program in 1 toting I is "como -ostring 
string.c". This script works well for small programs that only need 
linking with a few libraries. If your programs require include files, link 
libraries, and object files from several different directories, you will 
need to modify the script, or use a "make" file to compile and link 
them. Listings 2 through 5 are sample make and link "with" files for 
compiling and linking C*» programs using Comeau C" andSASC 
The make file in Listing 2 and the "with" tiles in listings 3 and 4 
compile and link a C+- program, and the make file in Listing 5 
compiles and adds C- • modules to a link library. 

The c30 directory contains one utility program, named 
include, and the three programs you use to compile C • * source files. 
These programs are depp, (front, and slid depp is a C preprocessor 
written by Matt Dillon C preprocessors prepare C or C»* sour." e files 
for compilers Preprocessing involves remoi ing comments, expanding 
macros, merging external files into the source file, and performing 
various other functions Any C preprocessor that is ANSI compatible 
and recognizes BCI'L-style comments <"//") works with Comeau C« •. 
but the recommended preprocessor is depp It is f.ist. reliable, and 
accurate. 

cfront is the actual C»* compiler. Comeau's cfront is ■ 
licensed port of AT&T's cfront The Comeau port supports C** 
templates, a feature of C»* documented in the reference manual as 
experimental. Templates .ire "super -macros' that cfront uses to 
automatically generate parameterized classes and functions Using 
templates, you can create "families" of classes or functions by defining 
a single template class or function that accepts ,i type BS I parameter. 
You specify the actual type lor the intended class or function .\s a 
parameter in a template declaration, cfront automatically genera te s 
code for a class or function of the specified Ivpe from the template 
Templates are somewhat similar to standard C macros, but they are 
much more powerful 

The third program you use to create a C-- program with 
Comeau C* « is stid. Versions of this program are provided lor use 
with both the SAS and Aztec compilers. The A/tec version is named 
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aatid 1 think the name of the program to an abbreviation <>t -un. 
initialization and destruction." The documentation tor Comeau C* • 
does not discuss slid in any detail It is the part ol the compiler 
package that installs procedure calls to Initialize and destroy static 
global objects. It generates a C source code file containing a procedure 
named _ConStrucT(). The Gt • compiler places a call to this procedure 
in mainOso th.it it is called as soon as a C » • program begins execut- 
ing. The compiler also generates functions that call constructors and 
destructors lor statu global objects _ConStrucT() calls the Initialization 
procedures when a C++ program begins execution, and arranges for 
the Cleanup procedures tO be called when the program exits. I low does 
itid know the name of the procedures that cfront generates so they can 
be called by _ConStrucT()? It finds the name- In examining the 
program's link map The names of the procedures cfront generates to 
call nW constructors and destructors for static global object- are 

(i d with " -ti " and "_sid_". res p ec ti vely. stid looks at the 

symbol- in the program's link map and generates calls to the proce- 
dure- it tinds whose names contain these prefixes. Because slid needs 
to examine a program's link map. creating a C+ + program with 
Comeau C++ requires two link steps. The first link step creates a link 
map of the program's symbols. After this step finishes, slid executes It 
creates .1 new source code file containing _ConStrucT(). This source file 
is then compiled (using your C compiler) and the final link step is run 
to put everything together into an executable program 

The utility program in this directory, include, is used during 
the installation process to create the Comeau C + + include directory- ll 
Can also be used in a stand-alone mode. The C++ compiler encodes all 
names it finds in a source file. II does this to support overloaded 
function names (the same name is used for different functions) and to 
implement type-safe linkage Most programmers refer to C« >'s name 
encoding scheme as "name mangling " There are two problems that 
result from name-encoding First, if references to symbol names in 
existing libraries .ire mangled, the linker will be unable to locate them 
and link the program Second, it you are debugging a C++ program 
with a -011 ice- lev el debugger, the mangled names recognized by the 
debugger will not correspond to the unmangled name- in the source 
file. The first problem is easily solved You prevent cfront from 
mangling the names of existing C variable and procedure names b) 
declaring them as follows: 

- - 

ibics and functions 



Ifce simplest way to protect existing C variable and function 
names from name encoding is to protect the entire header file in which 
Ihey are declared; 



extern "C" I 



' 



This is exactly what the include program does It creates , 



c • • Include director) that parallel- your existing C Include directory. 

Each C-M include file simply protect- an existing C include file of the 
same name The second problem resulting from name encoding is no! 
BS easily solved as the first problem. Its solution requires support for 
name unmanghng al the SOUKC code debugger level This level of 
support must be provided in the debugger, and SAS's Cixiel'robe 
debugger does not decode mangled ('•• names. There are tiller' 
utility programs that unmangle encoded C • * names, and the Comeau 
documentation refers to an unmangler program named comofilt 
However, this program is not included with the AmigaDOS version of 
C++. 

The mcludeM sub-directory contains the Conu-.m t '- . 
include files These are C- • \ er-ions of the include tiles m your 
standard include directory (generated by the include program 
discussed above), several Comeau include files, and include tiles that 
are part of the C++ Language Sy-tem trom AT&T 

The lib lit sub-directory contains two link libraries One is lor 
SAS C and the other is for Aztec C. Both libraries contain ports of the 
stream and io manipulator procedures that are distributed with C++. 
pin- other procedures that are part of the core distribution of C++ 

COMPILING AND UNKING A C++ PROGRAM 

If you are compiling and linking a simple G • • program, you 
can use the rexx script provided with Comeau C+ + . This is the easiest 
way to use Comeau C++. If you want to create vour own C++ link 
libraries or link a complex program, >'0U need to know how .ill tin- 
programs described above work with each other and with vour (. 
compiler and linker. Following is a -tep-b\ -Step description of how a 
^ • • executable program is generated (steps are for SAS C, but the 
steps (or Aztec Care similar): 

1 . Create a C» + source code file. 

2. Preprocess the source (ile. The preprocessor recommended 
tor us,- with Comeau C++ is depp. The generated file name has a suffix 
ol ".p". 

3. Translate the preprocessed C++ source file to create a 
temporary C source file. This is done using cfront. The name ol the 
generated file has a suffix of "c". You should not place this rile in the 
same directory with your original source code file, unless you modifv 
the name. I place the file in the Tr director) and add a "T" to the end 
Of the file name. 

4. Compile the temporary source file generated in step ' 
using your C compiler. 

5. Generate a symbol table for the program with a linker 
(blink or slink if you are using SAS C). The default name for the map 
file containing the program's symbols is CCprelink.map I use the 
name of the source file with a ".map" sulfix for the name of the map 
file. 

6. Run stld (orastid). Input to this program is the map file 
generated in Step 5. This step create- a source code file to take care of 
static Initialization and destruction. The file name is the same as the 
name of the original source code tile, but the name is prefixed with .111 
underscore 
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7 Compile Ihe file generated In step 6 

B Run a final link. Ihis itcp links .ill the object files 

generated m the atxn >• steps and an) required library procedure- to 

produce an executable C+# program 

I Istlnga 2 through 4 contain .i make Bl« and "with" files lor 
compiling and linking the sample Siring program these tiles show 
how the steps listed above arc used W compile and 'ink a < • • 
program The make and with files are foi version 6ol theSAScompUer 
and llnkei Creating a link library bai i • i source files Is similar to 
creating an executable program, [he only difference is th.it the object 
moduli** are placed Into a library instead ol being- linked into a 
program Listing q is a sample make file for compiling several C+ - 
source files and placing the object modules into .» library. 

I nit UAfl \TAT10N 

The documentation lor Comeau C+» is sparse. Most ol it b .< 
reprint ot the t- * i reference manual. The "User's Manual lor Amiga- 
DOS" portion ol the documentation consists ol an overwhelming total 
ot eight PWCT lluee ot these eight pages are "man" pages tor running 
como rexx, and two pages .ire Installation instructions. In all fairness, 
Ihe documentation is adequate tor compiling and linking simple C** 
programs. It also documents all the different input flags (or the 
programs dix. iisn,\) above, and discusses some potential prob l e ms you 
may encounter tf von are using version 5.10 ol 5ASC with Comeau 
t - - However, there is no documentation th.it tells you how to create 
your own C+ - libraries or how to link pro g rams with libraries other 
than your standard compiler libraries ind ihe C++ libraries You have 
lO examine como rexx to figure out how to compile and link a complex 
C++ program or creates link library As an alternative, you can refer 
to this article! 

SUPPORT 

Free technical support lor Comeau C++ is available in 
several different forms You can write or call, or obtain support 
through WX. CompuServe, Prodigy, "r Usenet. I called once to ask 
several questions My call was returned within several hours. The 
person with whom 1 spoke w.is polite and courteous, and I was 
satisfied with Ihe answers lorm quest ton- 

SYMf WRIOUIUi Mi VJs 

In use c omeau C++, you will need at least 1MB of memor\ 
IrtC( • * compiler, ctront is over ^MH in Size, and requires about 
loo.OOi) In ti-s ot st.uk space I would not recommend using ( • * 
without 2Mb" of memory and .1 hard disk You can conceivably use 11 
without .1 hard disk, but you will probabl) need enough memory to 
load ctront and sUd Into RAM. You will also need enough memon to 
run your ( compiler and linker 



mm him noEst om lift 

IT? 



work.. -\\n m n\ t mint n js 



I have used Come.ui l 1 < tor six months i have created 
many small programs and C++ libraries With Comeau C++. To really 
test Comeau C« f, I used it to compile a large, complex, UNIX- based 
C - • program that 1 transferred to my Amiga. I have experienced no 
problems WithO *. and .is fin* as I cin determine, Comeau I 
faithful to the Specifications in the reference manual ltiis un- 
expected since cfront Is licensed from AT&T, but problems can (and 
do) creep into software during porting I did encounter two problems 
using ihe ~> 10b version of the SAS • compiler I reported the problems 
to SAS, and they acknowledged that the proble ms were C compiler 
bug- Itoth of the problems .ire fixed in Release d ol the SAS C 
compiler. (Release (• of SAS I is excellent!) 

The Release 5 version ol the CodeProbe source- level 
debugger does not work with Comeau C++, bui the Released >.. 
works |ust fine To use the debugger, you must use the "Sou reels" 
compiler option to get the name ot the original t - • source tile placed 
into the object module. Otherwise, Code-Probe thinks the source file 
von an! debugging us the temporary C file generated bv ctront As I 
mentioned above. C odel'robe does no! unmangle symbol names -o 
you need to look at the temporary C tile to determine Ihe mangled 
names ol the symbols you .ire interested in examining with the 
debugger 

Some symbol names in the version " SAS libraries SI* 
different from their version 5 names They were changed to conform to 
ANSI C requirements. As a resull of the name changes, il you link n iih 
libraries created with version 5 ol the SAS compiler, you will get 
"undefined name" errors from slink Ihe correct solution to this 
problem is to obtain a "patch" to the libraries I contacted Comeau, and 
was told they were sending a library patch to support version i. ot SAS 
C. This problem can also be corrected by redefining Ihe old symbol 
names to their new names. The link file- in listings 1 and 4 show how 
this is done lor ihe symbols in the Comeau C** libraries thai were 
renamed 

I wo sets of library classes and procedures th.it .ire pari ol 
the C++ 1 arotuaee System on most UNIX workstations are not 
included with Comeau C* • these are classes and procedures th.il 
Implement co-routines and complex arithmetic Co-routines unple 
ment a parallel processing algorithm using .1 "task" class Coroutines 
execute sequentially instead of in parallel, but programs th.il use the 
co-routine procedures are easy to port lo architectures that support 
parallel processing The complex arithmetic classes .ind procedures 
implement complex numbers (numbers lhat have a real part .ind an 
imaginary pan) Both of these -vis ot classes and procedures address 
specialized problem areas. These classes and procedures are not part ot 
Comeau C-*. This is not ,1 serious OinlSSiOn (unless you *tt writing 
programs that require them) Otherwise. Comeau C++ Seems to be a 
complete port of AT&T's C++ 1 .ingu.ige S\ stem 

OVERALL EVALIUTION OF COMEAU C++ 

Here is how 1 rale Comeau C-- 



rechnkal qualit) and reliability 


excellent 


Price 


good 


Support: 


excellent 
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Installation: 

Documentation 

Completeness 

Integration with AmigaDOS: 

Integration wilh ( l ompilers 



excellent 

poor 
exceilenl 
excellent 
excellent 



■no above ratings ate entirely subjective, and other than 
pme are based on comparing ComeauC •- with the professional 
pngrnnrningtoolsandcoinpUers l use on i NIX workstations. 

Compared willi prices fof< H development svMem>.on l'\l\ 
workstation* (around $3X10.00), even the price of Comeau< • • li 
exceDenti Except few the documentation, I .im entirely satisfied h Ith 
c omeau C++. 

rURTHER READING 

It \ou ue interested in learning more jKiiil ( • -. and about 
( • • Release 3.0 in particular, TheC* - I'rogr .miming language, 
second edition, is an excellent .mil Intere stin g source ol Information, lis 
author is BfarneStroustrup, the "father of C++." li is published K 
Addison-Wesley, Ihebook has over MX) pages and covers all aspects 
ol revision .10 of C++, It also contains the entire C++ reference manual 



Listing 1. Sample C++ Program 



* 



• 



■ 






• 



■ 
* 






■ 
■ 

■ 

■ 
frlana .. 









■ 



■ 

■ ■ 

■ 












■ 



■ 









Listing 2. string. make 






I [■ l Bl . n a . Nk» 

1 

-.T 6.0 

1 

turns ■ : 
I 

■ 
1 
■ 

■ 

crertM 

■ ■ ■ 

i 

MMU 

• I- i 



SIOBJI \ 

■ 

■t*p» 
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■ 

I dalti 

■ 



■ 

■ 
I 



Listing 3. string. Ink 1 



■ 

■ ■ 



TO »t ■ 

■ 
BVldl 



>cwr 



Listing 4. string. Ink2 



prograa 



TO «t : 

■ 






■ 



Listing 5. linklib.make 



* 



■ 
■ 

■ 

CFLAGS 

■ 



I'll 

■ 
* 
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Forest W. Arnold 
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P.O. Box 2140 

Fall River, MA 02722-2140 
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SysLog: 



Wh.ii the heck is a an ARexx command host? It is a question 

often uttered by beginner ARexx programmers as they wade their way 
through i hv ARexx User's re fe rence manual Well an ARexx command 
hOSl b usually an application program which commonly h.n Kvn 
written in <_ or assembler .mil accepts commands via an ARexx port 
Theuset specifies to the ARexx which command host to use with the 
"address" Command, ARexx will then send any command found in an 
ARexx s.npl which it is docs not recogni/eon to the specified host In 
this way several applications which supply ARexx ports can be 
"glued" together with ARexx to provide super-applications Abo, 
several applications now use ARexx u their macro language, where 
the ARexx ih.hh'> that a usei writes are sent to the ARexx interp r eter 
which in turn sends commands back to the application to perform the 
user's wishes. 

Il is also possible to write simple command hosts in ARexx 
itscU Why would somebody want to write a command host in ARexx? 
As ARexx is in mierperaiive language, nist like AmigaBasic, and thus 
Can be Vejy slow when compared to programs written in compiled 
languages like <. or assembler, it would seem strange to write i host , t1 
ARexx, While this argument is true, there are advantages to writing a 
command host m ARexx, if cmiv just to prototype the final application 
Since It is utterpentive, you don't have to compile your program and 
you save tune while trying out new idea- ARexx also has an intone- 
th e debugger, built-in functions which make it easy to write ■ 
command host It is a great way to team a bit more about the way m 
Whidl ARexx works 

The r-'st of ilus article will show how to write a simple 
ARexx command host * Inch can be used to log from other ARexx 
scripts to a log file Ihis is.i similar application to the one descri b ed in 
Brian /upke's article "Message Logger" in the August 1941 issue ot 

tipitlm^. In Mr /upke's article, however, alt programs are 
Written in C and do not use an ARexx port 

The use of a log file is very common in operating svstems 
such as L MY where .m\ error-, or system messages are saved to 
various log files <>ne such file is know as the "systog" Rle A pn 
running under the UNIX Operating system can write to the log file by 

making calls to special library* functions AmigaDOS does not have 
such a Facility but as Mr Zupke's article shows, and I hope tin 
will as well, it iseasvto odd. Our ARexx command host will add 
messages sent to it. together with a time stamp, to a log file You will 
be able to add commands to your ARexx programs and even vour 
shell scripts to send messages to the logger host for inclusion In the log 
flic, 

You may well ask. Why don't we heft write directly to the 
log file* Well. AmigalXJS like UNIX is a multitasking operating 
system, so n is possible mat more than one proce s s will try to write to 
the log file at an) tune If thlS were lOOCCUT.a number ol things might 
happen; Kith writes could work, one write could tail since the file 
could be locked by the other process or the messages will appear 
intermingled m the log file So some sort ot control is required to 



"serialize" the log requests On I nix systems this control is supplied 

0) ,1 -.(*•, ial deamon process know is "syslogd". Tins process accepts 
messages sent to It by other processes and writes them to tin- ruconeal 

a time. The logger host will perform a similar job for the Amiga 



Our simple host will accept, via a public port, two commands: 



On receiving tins command the logger will write the 
"message" together with a time stamp to the log file, "SSVSlog" 

Ut_STOP message 

On receiving this command a shutdown message will be 
output to the log tile, together with a lime stamp and the Contents or 
message" 



It is very important that all packets are 
returned to the process which sent them. 



I isting i. logger rexx, is a complete listing ol the ARexx 
logging host, which you may want to type in now and try out ARexx 
must already be running on your machine before von can st.ut the 
logger. If ARexx is not alreadv running, you can start it from a shell 
command line with 

rex- NIL: 



lo start the logger itself, use the following command from a shell 
window 



■ 

lb chert that the host has started have a took m the log file, 
"sisyslog". Ibf a startup message You can add messages to the log file 

from a shell « indow with the following 






. 



li you now look ai the log file, there should be another e n lr) 
"JUST A TEST", added You could also use the ARexx program in 
Listing 2. "log rexx . to add messages 
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An ARexx Host 

for Logging Messages 



By Paul Giltings 



rx log Another Test 

The above will add another entry to the log file which will say 
"Another Test" 

The following line when added to an ARexx program Ml ill 
log the messige "a log ni.-sk.igc" to the log file: 



LH_ 



To shut down the logger, you have two choices; you can use 
the program in lasting 3. "stoplog.rexx". or you can enter the following 

in i shell window; 

ix -'Ui_STOP' Bye!' 

If you intend to use the logger in your system you should 
copy the three ARexx programs to "REXX:", assigned to the directory 
where you keep your ARexx scripts. You should also start the logger in 
your ~s;startup-sequence". Users of 2.0 should note that "rexxmasl" is 
not run until alter the "s:User -startup" has been executed. These users 
will either have to run the logger from 'Vstartup-scqucnce" (after 
rexxmasl is run) or move the line that runs rexxmasl to their "s;user- 
startup" tile 

Now you've wen the "logger.rcxx" in action, let's have a 
closer look at the code; you might want to read the sidebar "ARexx 
programming in Style" to better understand the coding conventions 
that I have followed in writing these scripts. The first major piece of 
work is to ensure that the ARexx support library "rexxsupport. library" 
is present, since the logger host will use several functions that this 
librarv supplies 

if( - Show ( "Libraries' . "rexxsupport .library" t ) then 
do 

- AddLibt "rexxsupport . 1 ibrary". 0. -30 ,01 
) then do 

call OutputLogMsqt 

"SysLog: ERROR : Cannot load 
Rexxsuppc ■ ' . bi iry'l 
20 
end 
end 

In the above, a check is made to see if the library is loaded. 
The "ShowO" function will return a Boolean flag which indicates it the 
specified library appears in the system's list of Libraries. Since the 
check is tor the instance where the library is not there, the return code 
from "ShowO" is negated with the "-" operator. If the library is not 
present, it is loaded by a call to "AddLib". The arguments "0, -30, 0" 



are taken from the ARexx manual and you need not worry about them 
other than getting them right It tor any reason the load fails, an error 
message is displayed and the program exits. 

Since the intention is that other processe send the host 
messages, the host needs to create a destination (or these messages 
This destination is a public port In ARew creating a public port is 
easy; -ill that is required is a call to "OpenPortO" with the name of the 
port to be created. 



OpenPort (OURPORTNAMEI ) then do 



port"! 



exit 23 



end 



The variable "OURPORTNAME" has the value "SYSLOG" 
so the port that was created is called "SYSLOG". Again the function 
"Createl'ortO" returns a Boolean value and, OS It good practice, this 
return value is checked. If the returned result was false, then some 
error has occurred and the port was not opened. One reason why a 
port cannot be created is that a port with the same name already exists. 
If the port could not be opened, the program exits 

There is one last thing to be done before the host starts 
processing messages and that is to log a startup message in the log file 
with a call to "Output LogMsgO". 

Call OutputLogMcg ( "SysLog: Startup* t 

Before you run off and look this function up in your ARexx 
manual, I should tell you that this function is an internal function to 
the logger host and can be found in listing 1. The function starts at the 
label 

OutputLogHsg: 

I will come back to this function a little later. 

The logger host has finished all its startup preparations and 
is now ready to process messages Messages arrive at the host in 
structures called packets and until the host receives a packet there is 
nothing to be done, so the host waits lor a packet to arrive 

call WaitPktl OURPORTNAME I 

The "WaitPktO" function will not return until a packet is 
available at the named port. When a packet Is available, it should can 
be pulled off the port's message queue: 

Packet «GetPkt( OURPORTN.v 
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"Packet" now contains the address of (pointer to) a message 
structure. It turns out that on occasions ■ WaitPktO" returns when there 
is an empty packet on the queue. These packets seem to be generated 
by ARexx when debugging is turned on via the program TS; here may 
be other occasions as well. The host should ignore empty packets! If a 
packet is empty, then the pointer that "GctPktO" returns will be a 
special pointer, a null pointer A null pointer i> .1 pointer which points 
to nothing. 

ARexx supplies a function, "NullO", which returns a null 
pointer. So to chock if "Packet" contains a null pointer, it is compared 
to the value returned by the function "Null()". If "Packet" contains a 
null pointer, the logger goes back and waits for another packet to 
arrive. If "Packet" does not contain a null pointer, the command that 
was sent to the host is retrieved from the packet by a call to 
"GetArgO". This returns the command and the arguments, sent to the 
host, as a siring. A parse instruction is used to split the string up into 
its constituent parts. The"parse" instruction will search for the first 
occurrence of a space, " . in the string; Even' thing before this space is 
assigned to the variable "Command"; everything after the space will 
be assigned to "LogMsg". To make processing of the command easier, 
it is .ilso converted to upper case. 

if( Packet -= NullO I then do 

parse value GetArg ( Packet ) with Corwand ■ " 
: >gMag 

upper Command 



It is very important that all packets are returned to the 
process which sent them. The process which sent the packet will not be 



Side Bar: ARexx Programming with Style 



I h.v. rj programming in \Ke\\ and one 

of Ihe ■ I did was to create an "ARexx programming style 

guide. 'Style is Usually a ■ ■-. cars, manners, etc, but 

not with programming- So what do I mean by a program" 

A programming i ■: rules, or guidelines, 

l program Mo>t software departments 
in com c Men their program 

:: their code. The aim of these rules 
is to make the code easier for the programmer and 01 i This 

allows programs. ip code written by other programmers 

and for them to feel comfortable with the layout of the programs This 
i- mtv important a- it is usual I >de to be reviewed Inn 

walk-througl . no or 

little involvement In writing the code The purpose of the revfeu 

walk" through the code a line ai Ihe time figuring out 
what the pi. . en though the 

j write ma j 

■ lumto 
a program to add or modify feahiri 

Another reason reduce bugs and 

d lnni' 1 Ago i 'inotcs good programming 

ding methods which introd u 

The following i% a basis lor .m AS this 

guid>- me You may find some of the rules awkward or 

g feel free to modify th. ■ .eedsbut 

■ 



COMMENTS: 

The first rule b <rta 

program with aioinnu'; rv) people w mment 

; entering 



Wtial did put in the first comment is the name of the 

ARi-xx script klngal a printed listing you la 

which script It is a print out oj Uonofwhal the script does, a 

description of the command line arguments, and an example o( how to 
run tlie program 

Don't be shy with your comments; the more you put in 
whm you write vour program the easiei it will be to understand the 
program Ul 

If a comment is multiple It Mrt and end the 

comment oi\ a separate 



■ 

rhis allows Unas to be added anddel<-!< Uso, indent 

nmenl so that (he textual part stands out. whit 
nit in programming as in writing 
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able to run uniil the packet is returned. To return [he packet, one uses 
ihe "ReplyO" function What returning the packet ■ return code" cm 
also be specified a non-zero return code Indicates th.it something 

went wrong in processing Ihe command. Since in our simple example 
the sending process will not be checking (or .1 return code, we will jusf 
return 0. 

call Reply (Packet, 0) 

Al this point in time the host now has .1 command and a 
message to log. Processing of the command is fairly straightforward. 
I Tie select" instruction is used to compare the command that was 
received with the commands thai the host understands If the 
command received was "LH_LOG"' the host will simply log the 
message If the command had been "LH^STOP". a shutdown message 
would have been logged, the host's port will then be closed and the 
program will exit. If the command is neither of these, a message is 
logged to to Ihe log file saying that an unknown command was 

received 



select 



I OCjMSCj 



I Coranand — "LH_STOP" I then do 

call OutputLogMsgt "SysLog: ShutDown: 

CloBePortt OURPORTNAHE 1 

■■ ■ 
on i 



measure TEMPERATURE 
wuu your AMIGA 



Uie your AMIGA lot... 

° 1 IMI'-ANIKTEMPfcRAIURE 

VIDEO DISPLAY 
•WEATHER REPORTING 
"GREENHOUSE MONITORING 
• LABORATORY MEASUREMENTS 
59990 lot erAO" temperature system 



sense MOTION mm AMIGA 

eiMOTION* is a minmiurc infrared motion 
dcleclor ibal connects to either Amiga guneport 

tzMOTION simulaies piettmg a left mouse 

button or joystick fire-button when a person enters 

ihe motion lensor's detection zone 



IIIFSFA OniFJI SENSORS A VAIlAtLE FKOM 

DOONE TECHNOLOGIES. INC. 

P.O. BOX 15052. RICHMOND. VA 23227 

PHONE & FAX (804) 264-0262 



Citcli IDS on Read*' Servica card 



NAMING CONVENTIONS 

-> .mablcs and fin tescrtptiveas 

■ If a name is made Up of Several words some people Sep 
the word- with an under a me. I 

think it is better not to use " " and W Capitalize the first letter of I 
word that makes up the name eg, LongVanableNamc FN 
luppUea no extra information to the name and requires extra t> . 
Using the capitallzt and variable 

names to stand out 

CONSTANTS 

I 
the fal 






gramma wants to use pi In -\ calculation he tx the 

can just use the rut * ' ier than typing Out "3.141" all the tune 

decided that the \ "ceds to be more accurate onl 

line ha rather than all the place* m the program 

ted Now for the bad news AluFucdottanothavanaimd 
constants ro get around I -esome 

indication th.it I variable is in fad intended to he a constant Valtl 
Onl] Upper* In the variable name: 



n 






• 




•\ i>. . . ' m attempt 

b made I nothervalut tarrl Since we are t 

variables Arex* on the other hand would see nothing wrong it j 

ed a new value to PI As >relul 

■ 

function lot each of 



These functions will just return the Value you WOuW have 
ted to your narnei 
which returns Ihe value of pi would look like 

Pit pi 

Toatv ■ have to make a call to the fun 

■ 



INDENTATION 

It has already been mentioned that text in comment'- should 
be indented Thecodl I 

be Indented 
is usually enough, with additional tabs for each level of nesting This is 
io help 
the various instructions m their nesting level 



"If." "else." and "select" 

illow you lo 
multiple Lnsrru rions with eacK using lh> * uchon. 

Knicuonsa 

a do 

Fui: 
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( Command =■ 'LH_LOO" I then do 
call OucputLogMsg(LogMsg) 
end 
otherwise do 

cal 1 gHsgf , 

"SysLog: Baddrd: " Cor 
end 



OutputLogMsg: proced'. 



LOG FILENAME 



end 



Th.it Bnishes the mam part of the logger host Now let's take 

a look .»l that function we ran into earlier, "OutputLogMsgO"- The 

purpose of "Output UigMsgO" Is to lake the argument given to It and 

writ. 1 the argument to the log file to g et h er with a time stamp, which 

consists of the date and the current Haw, 

In ARexx the start of a function is identified by a label which 
is the the name ot the function followed by a colon " Good 
programming practice dictates that you should try to reduce the area 
from which a variable can be accessed; the technical term for this 
concept is limiting the "scope" of the variable. In an AKexx program 
all variables are global and can be accessed by all functions, unless Ihe 
"procedure'' instruction is used. To prevent "Output I. ogMsgO" from 
having access to all the variables in the main part of Ihe program, the 
program USCS the following declaration for the function 



The "procedure" Instruction prevents a function from 

having access to any variable in the main part of the ARexx program 
other than the variables in the "expose'' list So Ihe only "'global" 
variable which 'OuputLogMsgO" can access is the variable 
"LOGBLENAMI 

The parse instruction is used by "Output 1 ogMsgO" to 
obtain the argument which was passed to it; 

Anybody who has tried to create a tile with ARexx krtOWS 
that there is no "CreateO" function To create a file in ARexx, one has 
to be open the file in "Write" mode. Be carefu.l however It the tile 
alreadv exists and you open it in "Write'' mode, you will delete the 
previous contents The following fragment |ust figures out in which 
mode the log file should be opened: 

if I Exists! LOG: I | then do 



sow prof* ertoi 

rich. 

"select" 

Again With DM 'ructions use the 

Instruc 

■ 

n do 
othei 

■ 
Whe several ahemativci use the 

K the intention of 
the cotr fo see and i- less error prone than mult. 

I 

last word on ti* mmand. Always include the 

"otherwise" branch and Include n | the 

"other.-. ited, include it and put in an mslru 

to output an error I how man) tunes that 

error ■ 'ping vour program' 

MODES 

umber of ARexx fun.t 
called "modes." A mode 

ndlt bused na function call 



Mans programmers chi 

How ■ served it 

Ihe entire string Is listed, as In 

(i- what we are interested in A general 
■ mining rui. (plicitj mtkeyoui Intentions as clear as 

Me 

FUNCTIONS 

You should place j cornmenl |ust before the starl 

ltd include the function name, the 
type of argument- vhal it will do If It returns* value 

ribe what it i- that il will return 
In ARexx all variables are global, meaning that al 
variabV our program an be accessed and 

■ pr a ctice; iusi 
think what Would happen it youi main program and one of your 

as used the same nam ■■ 
prevent a function from having ii variables 

the "procedure" Instruction alter the fun I 

This means that the variables in the in.nn part of the program are 
distinct from the vanabi, function Try running the following 

exami 
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AccessMode = -w 



<■:,! 



Finally, the log hie is opened in Ihe correct mode and the 
message together with a lime stamp is written out; 

■og FILENAME. AccesnMode) ) thendo 

' LogFile, Date! 'Ordered' ) Time! > Hag 

i 



end 



Thai is the host completed. ROW Ids turn to a simple 
example of how to log ■ menage with the host from within an ARexx 
program Tins ARexx program is called "log-rexx", listing 2 Youi an 
use it from within your Shell/Cli scripts lo lo£ messages with Ihe 
logger host. On*- use mifthl be to log when scripts are run ami when 
they finish. To do this add ihe the following lo your scripts 



I lie first thing that "log.rexx" does Is check the number of 
arguments lhal were supplied to it on the command lint? II no 
arguments were given, an error message is printed and Ihe program 
exits. Otherwise the parse command is used lo fetih the argument and 
assign it to the variable Msg 

It c possible in ARexx to do error trapping. Fhus, when Mt 
error is encountered, you can have ARexx tump lo a label in vout 
program You could then evaluate the error and do the required clean- 
up operations before exiting. One problem we could encounter m our 
log SCnpt is that the host is nol running. In AKcXX tins would generate 
a "syntax" error We would like to output an informative error msg 
when ihis occurs so we will trap all syntax errors 

. on syntax 

rhis line will cause Ihe program lo jump to the ">wiMv M label when a 
~\riM\ error is encountered. I"he code to handle this error is quite 
straightforward; 



rx log Pr- 

r.H t" 
rx log Prograr'. . ^ned 



syntax: 



say "Error: logger host not rui 
RC 



atuj count to 

out th< o 10 



do Count 

Ion: 
parse arg Count 

tarts at and we want tc 
out Ifl 
the main program. 



the function \U PrintFunctton" and the mam program So as well as 
bceing incremented m the main program, it ai- . mentcd by 

One ever* lime "M\ I'nnll million" is Called Rv adding the procedure 

keyword, the 'Count" variable in the MyPrmtl unction been 
distinct from the fount" variable in Ihe main DtOgl - ■ 

simple example and the bug Would BUl it you start 

writing more complex programs, problems like this would be harder 
to find so stamp the bugs out before they occur by following some 
rules 

You will find thai sometimes a procedure will «• 
a number of global variables which you don't wish lo pass .is 
arguments to the function; maybe the function needs to an ess ihe 
global variables thai von are using aaconstants it you fed lhal a 
lion needs to have access to a variable In your main program, 

which you don t Wish 10 pass as an argument, you should declare the 
variable in an "export" lis! M 



G 1 coo IVar i abl eT\*o 






Count ■- c. 
say C 
urn 

It you run the above program (rx Silly), vou will find thai it 
does not print oul the numbers t rum 1 through to 10. It. howevel 

change ihe fine 



to 



KyPr intranet ion: 

H^' Print Function: procc 



and try run ihe program again it does print out ilw numbers i through 
It) in the tirsl version the variable "Count" variable is shared by bolh 



I hi- above allows the Junction to access the only global variables 

.Variable' .uui "ClobalV.uiablel wo ' So 'I Ihe function mad,- ■ 
re f erence to "i flobalVariablc," ARexx knows that it is to use ihe 
"Global Van able " m the main part of the program and not to create a 
ilobalVariable" for theexdusfvc useol the fui 

Ihe above should help vou create youi own style rules. You 
maj be wondering ii I really follow mh* my 

code! Have a look al the ARexx code bi the article "Sysl og \n \Rexx 
Host tor Logging Messages ' Did i foOov. all the above rules? Didyou 
consider llut by foil.. win,; the above guidelines I luxe actual! v made the 
code more readable, oi not? vVerethi wan) other style rules that you thank) 
followed in the article which an- not mentioned above? it's pusMbk*. once 
you develop your own programming >t> le and fou 

almosi torget it'stlinv but otliers can still - • -PG 
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Courtroom 

Legal Affairs Game 



1 Pity F"ihiiii- ot Orloir Aitmrri 
1 ft<m I ihoil/Caawn in. i 1.4,, 

• Uttit t. .-.mi <i.<. '•«■ Dntd 
1 1).' ...— Wixitx R a ,.r l*j..n n -. 
1 r«i>MNf ik. I... *.» iiv Cm 
■ i«d a> Fnb'il tiiki nf F<t«r iwt 

1 f"K<'«»»"I »"ll EdWMKHtll 




Origtnally $59 95. now on sale tor $39.95' 



Audio Gallery 

Talking Picture Dictionaries 




Each A **<• Cafirrj mlKldiU mi •>» «I1 Ml) 
diaHirrd wwdi lo hutld vocaNiUry in ■ fiwrtjn lanfuatc 
Vtnoni Ntfxt tuch at wrtOrt. lit mp mm k ikhcn 
nunwrn . etc are nt m nkc d in a fun crapftxal ton* it Each 
wi in. ImVi pammar manual, i*in>/t> and dKlnMUf) 

English, German, fitnch: n-g ssa nmnts 
RiHian. Kcreai. Japanese R»g$i29»ro.»95 
(hmiwk Sab! Spanish: W9.95! CMmm: 179 «■ 

Digital Orchestra 

IFF Sound Sample Libraries 

JV^ Compute 
• 4gi *ithMED. 
AfhaBh SoundTrrtief 



Sampled a| 

1?B97S/Sec 




SMI «i»r-i-.. SliplUx rnoV" Mnl (■ 
SM2Bf*a tiiNi T n ri...Tf» ifrt frr-MI... i* 
SMI "(V* - CVmp. ()*■» *U..tV..v "-«... ,v 
SMMSninp V.taV*,((»,i««lli.(« 
SAM (Jvaan ■ Ainratc. IMlr> 1/M.lwi <■ 
SMbFtam r«r- l»~. Tim ItM) t.Mn 
SAO' laii rvita.i-' I .tHhatr. Co»i i Bnnpi. nc 
tAIVIkwM I naoOwB Wi.I<- Co-t.ll.™ 
SM"l*wi«? Hi kH (Mi IpTilfMU n 
SAUIIV-.-.—. MrrMlv. I**.. Hell **..■*.( ,i, 
SAHOraa- IMitillMv. IMnKlmld; 

ui:rm> wiMHq n ..>r«,,ii. rn 

SAHnrft* M—Wi. l)tf<.n ("dMin 
SAMPI^n "•IVii*i.IbiWh «Htn 
SAKFnvwNr O-Mlrf Simfi V,,. *.*.(>*. n, 

SAIftOaan Tkwt a mnw tmui mi mm — wt» 

SAITlmCW* Hw. H« « M • i> 
SAI'OxKfOnvd. M.p*. Mia- M»)W )»■■ 
SAIVUrjaB Clmnh - CWtk <bian nl t ..»« <kav 
SAW S)«hn>ml CaA-*r V*** «Va>f . S» Ww. m 
UH O «1 ■ >««h IMw WmKfi V «. r« 

Cadi da* « pnoad at |4 s& l tor S3 « aadv Mn to. 

*?9 9S ComptoX co— con to- S69 » AHo avariaCM 

PD U**cai ( <**» program* and uMHxa S*"dto>l>** 
carpMHHnrq ShCQlna S3, km o> mora **i |4 

^,<«'^ The Sorcerer' s Appienlice 
k*ltG+ -W54 Son/n ??n<f Street 
^aak * Artinglon 1/4 7«06 

17031 etO- 195*. F« f 703) BM-4779 

II rail AifclM l.('X> If-t ?U(U, Au (nb 
1 Jl» •( r** 1 "! « {"■Mdun •**■* iKma tub 

*T»"* Om»v™«r*.«*i»«»ilT Mtil—— » «mPO .a mf d 



RC b a special variable in which ARex* store* an error code after an 
error is detected 

When .in ARexx script is run the default command port that 
it sends commands lo Is REXX. So the script has lo change the 
command port to "SYSLOG", me logger's port Hits is accomplished 
by using the "address" instruction; since the port name ^ stored in .1 
variable, th«> "address value" form of the instruction is used 

Not all commands one senl to the Logger host ro send tin- 
logger host .1 "log" command together with the message, you need 
onl) saj 

•LH_LCG' Hsg 

H> switch tin 1 command host back to REXX, »«• use another 
form ot the "address" instruction; 

address 

I hi-, version ot the "address" Instruction switches back i>> 

tin- pn*vious ironmi.ind host; U v. were t»> use it again, we would 
switch bacjc to the logger 

Ihe above three comm.indstmiKl W v\rm,>nasone 
instruction, yet .lnotlior virsum i>( thr 'address" instruction. 



i% ill s<.'nd just the one command to the Specified command host, 
wlthoul changing the current port \(»|] In this torni ot the "ad- 
dress" instruction the name ot the port must be stated explicitly; you 
cannot us,- .1 variable, lor example, die following won't work 

address I.0GGF!- 

This will instead try lo send the command to 4 port named 
"LOGGERPORT". And the following will result in a syntax error 



The program "stoplog.rexx" is cpiite straightforward and 

you should have no problems figuring it out lor younteli You should 
now know enough to add your own commands to the host. Trv adding 
a command to copy the contents ol the current log file, Sttyslog 
another hie. "s syslo>;.old" 

If you have any qin-st ions on anything that I have presented 
above you can drop nw a line c/oAmJzidvtiniif'iififiy or it you have 
aCCCSS to ACSnet or AARnel, my eleclonic mail address is 
paulK0tplrd.tpl.oz.au and on Internet it is paulg#tps i om 



BiBLICKiRAPHY: 

ARcw User's Rejemtce Mutual by VVUIIaro Hawes, 1987 
■sigo Logger" by Bnan Zupke, Arflflzrng Computing, 
August 1991 

Usfnj rVRexron the Amiga by Zamara and Sullivan. Abacus. 
1991 



Ciiel» 113 on Raadv Service card 



Listing I 



■ ■ 
This is an Arexx 



Host which 

:;log". 



.'.< 



LH_LOG Message - Che message Is added to 
the log file 

LH_STOP Message - the messao- 
the log file 

and then the logger 
shucsdown. 

To run this host use: 

run >NIL: rx logger. rexx 


LOGFILENAME = "s:syslog" /* The name c: 

log fill • 

OURPORTNAME "SYSLOG" 

port ' 



check Co see if the rexxsuppc- 
loaded. 

If noc. cry and load :' . he loa ! ! 

■ ter 
logging some error msgs. 

if( - Show! 'Libraries', "rexxsuppc: . 
chen do 

- AddLiblTexxsuppor- . :/-, 0. -30 .0! 

> the:. 

call .- :. -iMsgf 

'SysLog: ERROR : Cannot load 
Rexxsupport . 1 ibrary" ) 
exit 20 
end 
end 



■ cannot creai • 
pore, loo 

failure and i ■ 



if < - orx-:.' * ■■'•:. . '' ■ ■ 

: Cannot 



Introducing the 
AMIGA 
SMART PORT m 

PATENT PtMWO 

Now you can enjoy A 
PC Stylo gam* port with 
TWO analog joystick 
convarto's. two separate 
digital ports tor the 
mouse and joystick, and 
AUTOMATIC electronic 
switching Us« (he solid state circuitry and 
SmartPortCal utility program to tune the Smart 
Port to get maximum performance from your 
analog JOYSTICK and RUDDEfl PEDALS 
Fighter Duel flight simulator included for a 
limited time 1 Send check or money order for 
$5295 • $5 00 shipping to 

H>actMDgHDMa«kK 

m* KartfuoM Gout, tkmtm, OA ; 

■a i*w siao74e 




CtDO 



Circle tO* on Reader Service card 



exit 20 



end 



'" log a sCarCup msg •/ 

' i ( "SysLog: Startup" > 

do forever 

• lit for a Message Packet Co arrive ac our 

Get Pkt I OURPORTNAME I 



• word is a "command" and the rest 
is a message to be logged 

then do 
pars*/ uPackec) with Command ■ ' 

■;'■:..■: 

..;.' ■ • : — . - : 



tat sent this message does 
abouC any errors. So we will 
return the packet now with a recurn 
code of 

call Reply (Packet. 0) 

• : igure out which command it is ... ■ 
select 

when l command == "LH_STOP"l chen do 
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MOVING? 




SUBSCRIPTION PROBLEMS? 



Please don't forget to let us know. 
If you are having a problem with 
your subscription or if you are 
planning to move, please write to: 



Amazing Computing Subscription Questions 
PiM Publications, Inc. 

P.O. Box 2140 
Fall River, MA 02722 



Please remember, we cannot mail your 
magazine if we do not know where you are. 



Please allow four to six weeks for processing 



call OutputLogMsgCSysLog: 
ShutDown:" LogMsg) 

ClosePort) OURPORTNAHE ) 
exit 
end 
when ( Comta: I -;.H_LOG" ) Chen do 

call OutputLogMsgiLogMsg) 
end 
otherwise do 

call OutputLogMsg I 

•SysLog: Bad Cmd: • Command 
LogHsg) 

end 
end /• select ■ 
end • 
end /"do foreve-: ' 



the following line should never be executed. 
However, it is 

good practise to include it just in case there 



is a bug in 

the above code 
v 
exit 5 



End of main 



OutputLogMsgt string ): Will add the string to 
the end of 

the log file together 
with a 

timestamp. 
............. v 

OutputLogMsg: procedure expose LOGFILENAME 
parse arg Msg 



Make sure the log file exists if it doesn't 
then we create it. The file is then opened, 
the msg is writen and the file is then 
closed. 



if( Exists! LOGFILENAME ) I then do 

AccessMode = "Append" /* file exists, Append 
to it •/ 

end 
else do 

AccessMode = "Write" /" file does not exist, 
create it •/ 
end 

if( OpenlLogFile, LOGFILENAME, AccessMode)) then 
do 

call Writeln*, LogFile, Date ( 'Ordered* ) Timet) 
Msg ) 

close (LogFile) 

end 
else do 

exit 10 
end 
return 
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/• 

log - sends a message Co the logger host 
usage: rx log msg 
where msg is the message to be logged by the 
logger host 
V 

LCGGERPORT = "SYSLOG- /* name of the logger host's 
port •/ 

/• was a message specified •/ 
if( ArgO == ) then do 

say "Error: No message specified." 

say " Usage: rx log <string>" 

exit 5 
end 

parse arg Msg /• get the argument •/ 

signal on syntax /• trap errors '/ 

address value LOGGERPORT /• set command host to 
SYSLOG •/ 

'LH_LOG' Msg /• send the command */ 

address /• switch back to REXX •/ 

exit 

/ 

• * ....................... 

/ 

■•.■.a. ■•■.....■*•.......■■.■••■•■■•■■■■ ■■■ ■.•■■■•■••*••••*•/ 

/' 

Trap on syntax error routine. Simply, prints out 
an 

error message, 
v 
syntax: 

say -Error: logger host not running- 
exit 10 



Address -It! 

For home & business! 

Create rosters, mailing labels, envelopes, 
rotary cards, address books and much 
more! Output to Prowrite* and 
Wordperfect® mail merge format, import 
from other programs, and dial from your 
modem. This program is loaded with 
features, and is easy to use. Works with 
1.2/1.3 and 2.0, and virtually any printer. 




mi 
25 Frontenac Avenue q 

$39 95 Brantford. Ontario or money 

us CANADA N3R3B7 <*&* 

(5191-753-6120 

Circle 111 01 Re.dc/ So'-ice <*rH 



Lisiint: 3 



stoplog - sends a shutdown command to the logger 



LCGGERPORT = "SYSLOG" 

if( Showl'Ports', LCGGERPORT) I then do 

address value LOGGERPORT /• make SYSLOG the 

command host •/ 

*LH_STOP' "from StopLog" /• send the command •/ 
address /• switch back to REXX 

V 

or::: 






exit 



Please write lo: 

Paul Giuings 

c/o AC'S TECH 

P.O. Box 2 1 40 

Fall River, MA 02722-2 1 40 
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itmapped 

raphies 



by II » ii 





Introduction 

On the Amiga there Is a well-defined standard for the 
exchange of bitmapped graphics, IFF ILBM. As robust as the standard 
is. it is still virtually unknown outside of the Amiga community. There 
may come a point where you will want your program to exchange 
bitmapped graphics with the "outside" world. If so, you will need to 
know what other formats are available, and what their strengths and 
weaknesses are. This article will look at several popular standards for 
various microcomputer platforms. 

Picture .Speak 

As with most niches of technology, bitmapped graphics has 
its own vocabulary. Here then is a quick summation of the terms that 
are used in this article. A pixel, short for picture element, is the finest 
division of an image that can be specified. A bitmap, in the truest 
sense, is a computer structure where an on-bit defines a pixel of one 
color, and an off -bit defines a pixel of another color, usually black and 
white respectively. However, in current parlance, bitmap has become 
synonymous with pixmap. A pixmap is much the same as a bitmap 
except that multiple bits are used to determine the color of a pixel at a 
given point. This is done one of three ways, as grayscale, palette entry, 
or actual data. A grayscale picture, by definition, deals only with 
brightnesses of white. A grayscale picture will tell a program what 
range of values it will generate (0-1, 0-15, 0-256), then the program 
maps those values to ones it can handle In a palette-entry picture, the 










IFF II B>l - Interchange File Formal 
InterLeaved Bit Map 

Before other formats are examined, a frame of reference is 
needed. Since most readers of this article are familiar with IFF ILBM, it 
will serve as the standard IFF II I'M was originally designed by 
Electronic Arts for their Deluxe Paint program. It has since been 
adopted, along with the rest of IFF. as the standard (or the Amiga. As 
originally defined It can handle up to 256 bitplanes of data. In the case 
of the Amiga, there was a practical limit of 5 bitplanes, since that is all 
the Amiga directly supported. The format uses a color-lookup table 
(palette) called a CMAP in which each entry can hold a byte of color 
information each for red, green and blue. The format is somewhat 
limited by having only a simple RLE compression scheme, and no way 
to specify pixel size, although it can specify pixel aspect ratio. (See 
sidebar on compression standards at the end of this article.) 



A look at bitmapped 
graphics formats 



data is not the actual colors, but rather indexes into a list of colors. In a 
16-coIor picture on the Amiga only 4 bits of data (representing values 
0-15) are stored for each pixel, but each of the sixteen colors is from a 
selection of 4096 colors (four bits each of Red. Green and Blue). This 
method greatly reduces the size of images. The final class of files stores 
that full actual data in the file. This method is usually used when there 
are more than 256 colors in a single picture. In the case of a 24-bit 
picture there would be no saving in having a color list like a palette 
picture because the index is the data. A reader is a program or piece of 
code that reads and understands a given file format. A writer writes a 
given format. 

Finally, a short word about color theory. This article assumes 
that you understand that all colors shown on computers are made up 
of differing amounts of red. green and blue light. Since this is so, all 
current bitmapped graphics standards revolve around this. But, on the 
horizon are bitmapped formats that revolve around the cyan-yellow- 
ma genta-and -black color model used by printers everywhere. 



For the Amiga, the specification was extended to handle 64 
colors with only 32 palette entries by using special "hnlfbnte" colors. It 
was also extended to handle the Amiga's speiial "Hold And Modify" 
(HAM) mode that allows for pseudo 12-bit (4096) color. These 
modifications allowed the formal to apparently handle more complex 
images than it actually did. and .it noticeable sa\ in^s of disk space and 
memory. But these solutions are very machine specific and somewhat 
scorned by the rest of the industry. Recently, support for "deep" 
bitmaps, like those with 12 and 24 bitplanes. has been introduced. To 
date, however, no modifications have been made to address the 
limitations in compression and pixel st/e oVnmtion 

On many levels the IFF ILBM formal is a strong one. The IFF 
structure is easily expanded and modified. The only reason the 
weaknesses of the format have not been addressed is due to a 
reluctance to "break" non-conforming readers. On the Amiga, this is 
the format of choice. 

GIF - Graphic* Interchange Formal 

GIF (pronounced J1F according to the specification, although 
1 have never heard it pronounced that way) was developed by 
CompuServe for "defining a mechanism for the storage and transTnis- 
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sion of raster-based graphics information This formal is perhaps the 

most widely supported formal ol all, in terms of computer platform-- 
It readily supports 256-color palette pictures with t* bits ol R, G, & B 
information for each color In this respect it is similar to the 1I : F ILBM 
specification It differs, however, in a number of other way*. GIF uses 

1 ZW (Lvmpcl-Zi v- Welch) compressfon. This is a powerful compres- 
sion method that modifies itself according to the picture, and is very 
efficient. The format also allows for multiple pictures per file, but this 
feature is rarely used 

When til I was created, one of the design ideas was to use it 
as a method ol storing tiles so that they could be examined as they 
were being downloaded remember that format was designed by 
CompuServe. To optimize, this, some fill's are stored interlaced. An 
interlaced file stores the ican lines ol the Rlc in ■ mixed order. In effect 
every nth line is stored sequentially llns was done so that the user 
could tell what the picture was when only I portion ol the file had 
been transmitted. 

GIF is a good format for exchanging bitmapped pictures that 
are meant to viewed more than printed. There are I'D GIF viewers for 
lust about every computer platform, but not many pieces of commer- 
cial software road GIF files 

1>I<» - f»l >l Imam- I or in n I 

The INK; lorm.it has it* origins in the GEM operating system 
from Digital Research Inc. (DRl). This is the operating s\ stem used by 
the Atari and by some programs on the IBM PC, most notablv Ventura 
Publisher While II is thought i<l as m exclusively black-and-white 
format, in its original specification it is defined as ,i RGBW (Red, 
Green, Blue and White) formal Currently there is a resurgence of 
interest in a Color IMG format on the Atari, but no one standard has 
risen to the top. For all intents and purposes, IMG is a B AW formal 



As a B&W format, it is very powerful, and reasonably 
efficient W'hile the formal only supports ,\ simple RLE encoding, it has 
virtually no header -only 16 bytes compared to a TIFF file. Also the 
IMG fomi.it defines the Size of the image's pixels in microns. This [g 
exrenwry important. One of the common uses of the IMG format is for 
scanned images. Today it is not uncommon to have a collection Of 
[mages scanned at different resolutions for different needs While you 
may know that one image was scanned at 200 dpi and another at 300 
dpi, the computer has no way to know unless the tile lolls it. This Is a 
major problem with saving scans in IFF ILBM format Of course, pixel 
aspect ratio is Implied by the pixel si/e. so in this wa) IMG equals, and 

su rpasses iff 

While limited to B & W images, this format is nonetheless 
alive and well t>n several computers. If you are dealing with mono- 
chrome scans and want a good format, but not the work associated 
with TIFF. IMG is a good bet. This formal is supported as at least an 
option by many image lile converters on microcomputer platforms. 

PC'X - PC Paintbrush tor mill 

The PC Paintbrush format Is a good example of the I'eter 
Principle applied to a graphics file format It is hard tosa) anything 
good about the formal other than it is widely supported on the MS- 
DOS platform Like several of Ihe formats in this article, including 
MacPaint and IMG, PCX is in wide use because it was one of the Rrsl 
formats available on its pljtform. 

When the format was created, the designers seemed to think 
only in terms of existing hardware. Scanners. B & W, let alone color. 
were scarce, and the existing display hardware was limited. PCX's 
compression. RLE, does best when dealing with long runs of the same 
color, common in hand-drawn pictures, but rare in scans. At the tune 
lb colors was also thought lobe more than enough, so .1 Ifi eoloT 



Sidebar: Compression Methods 



by Dan Weiss 



Compression Methods 

Virtually every bitmap image file formal uses some form of 
compression. There are two good reasons for this First bitmap images 
can bo huge, and furthermore they tend to comp r e s s rather well. File 
•5 in ihe compression comparison chart shows that both the si/esof 
tiles and the compression achieved can be amazing. Each of the 
formats discussed in Ihe article uses oiu' or more of the following 
techniques to reduce the si/,' ol their hlo. 

Itl I • Run Length Kncoillni* 

Many times a bitmap image is made up of large spaces that 
arc the same It could be the white background for a drawing, or the 
blue sky in -1 photograph. If the computer MOB such a run ot pixels that 
are the same it will try to compress it with RLE. ihe computer will 
first store an indicator code and a repeat number, then the byte that is 
to be repealed. This method usually catches runt of Ihe same color. 
But, if ihe data in the Into is the same as the next, as m an ordered 
dither or pattern, this format will also compress mixed color data 
Depending on the maximum run the implementation can handle and 
the nature of thedau. this can bea vesy good or very poor compres- 
sion technique This method is sometimes also known as PackBits IFF 



ILBM, GIF, IMG, PCX. MacPaint, PICT, and TIFF alt use this method of 
compression 

l./M - l>mpcl-/,iY-Helrh 

LZVV goes 1 step beyond RLE in that it can encode several 
bj ie> at once. Each time a byte is read in it is added to a string of the 
b) t<s that came before it and given a code It at anytime the computer 
can look ahead and see a series of bytes that matches a string it has 
already encountered, it will use the code instead This method catches 
the longer term patterns that may emerge in a scanned image. Some 
hies, such as File "b on the compression comparison chart, show 
dramatic results with this method, while others, like hie number 5, 
show little. This method can be further improved by using ■ predictor. 
Tins is a mathematical function that is fir*,t applied to the data before it 
is compressed A common predictor is ,1 horizontal differencing 
predictor. The predictor replaces each byte H Mh the amount it is 
different from the last in the original image. In this way it is the change 
itself that is being compressed. Due to the computation involved in 
handling LZW files thev tend to compress and decompress much 
slower than RLE Files. GIF and TIFF both use this method of compres- 
sion, though only TIFF uses predi, tors 
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palette was placed in the formal. With this 2-, 4-, 8- and lb-color files 
could bo easily stored. Since then, in response to new hardware, the 
format has been extended to support 256-color pictures. 

Unfortunately, since no provision was made to expand the 
format, the color palette was placed after the end of the file. As in the 
put the designers of the formal made some assumptions about the 
256-color extension The logic was that if you can have 256 colors, who 
would want less. Therefore any file over 16 colors is always stored as a 
256 color file. This means that a 32-color file is very inefficient because 
it has to carry around three unused bitplanes Even though PC 
hardware that existed when the format was created only supported a 
handful of colors, the designers did have the forethought to specify 
each color in the palette with a byte each for R. G &B for a total of 24 
bits of information. 

As I have said, the main strength of the format is that it is 
widely supported on the PC. If your need ls to exchange small files 
with programs that don't support better formats, then PCX is okay. In 
general, because of its lack of flexibility and poor compression, 1 would 
avoid this format. 

MacPaint • >la<-l»nlnl Flip Formal 

The MacPaint file format Is tied very tightly to the original 
Macintosh and its hardware design It is monochrome only. 72 dpi 
pixels only, and always 576 x 720 pixels. The reasons for this are 
simple, the original Macintosh was monochrome only, and the display 
and printer were both 72 dpi. The static file size made the file very easy 
to compress and decompress using statically defined memory 
structures that .ire relatively small (>52K). Also to aid anyone using 
this format, Apple built the compression software into the ROM. It is a 
simple matter to write a short program that reads and writes com- 
pressed MacPaint files — on the Macintosh that is. For the rest of us, the 



format of the file and the 
compression method. RLE, 
are reasonably well documented in non- 
Macintosh publications 

There is little reason to wnte files in 
this format. It is very limited since the document 
size is fixed, and the resolution is assumed to be 
72 dpi. However, it may be a good format lo 
read. On BBSs and PD disks across the world 

there exists thousands of megabytes of MacPaint files. One popular 
CD-ROM alone has over 30 MBs of MacPaint files. These files contain 
just about every type of clip art you can imagine and then some 
MacPaint files can often serve as a foundation fora larger graphi, . ,i 
brush, or some quick clip art. When used as 300 dpi graphics, the\ can 
be quite sharp, and of course, quite small (1 /4 original size). 

PICT - tlaclnlosh iMi-uii-c Formal 

Like MacPaint, the PICT format is tied tightly to the 
Macintosh and is used virtually nowhere else. As with MacPaint. I 
would suggest this as a format to read, but not write The similarities 
with MacPaint end here. The PICT format is first and foremost a vector 
drawing format. It was designed to encompass every drawing 
command available to the Macintosh In this way anything that could 
be drawn to the Macintosh screen could be stored in a file. This of 
course includes bitmaps In the original PICT format, only II & W 
bitmapped images were supported Because of the original limitations 
of the Macintosh, the PICT format often stores a picture as .1 series of 
smaller pictures. Also, to be sure that the picture is imaged correctly it 
may first draw the image once as a mask, in white to clear an area for 
the picture, then a second time to lay down the image This means m n 
half the information in a PICT file may be useless (0 vou 



CCiTT Group 3 - Fax Compression 

The Croup 3 format was specifically designed for compress- 
ing fax images. It takes a radically different approach from the two 
methods above. Studies were done on typical faxes, and the most 
common white and black pixel (bit) runs were determined. This 
information was placed in a table and codes were assigned for each 
run. Since the table is the same no matter what, it is buill into every fax 
machine. The success of the method comes from two areas, first 



because it is designed for the noisy data that is common with la.es and 
additionally because it compresses at the bit. not byte, level When 
decompression is handled directly by special chips, the speed can be 
incredible, but when handled it software it can be slow since it work-. 
at the bit, and not the byte, level. Only TIFF uses this method, and it is 
mutable only for BAW images.— DW 



Compression Comparison Table 






File* 


1 


2 


3 


4 


5 


Number of Colors 


2 


16 


256 


16.8 


16.8 


Actual Size 


52 


64 


92 


439 


900 


IFF 


32 


12 


96 


431 


163 


GIF 


26 


5 


42 


- 


. 


IMG 


38 


. 


. 


. 


_ 


PCX 


45 


12 


94 


_ 


_ 


MacPaint 


33 


- 


. 


. 


. 


PICT 


34 


34 


76 


443 


122 


TIFF 


26 


6 


44 


409 


67 


All Be sees ate rounded and shown in Kilobytes 
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Bitmapped Graphics Format Comparison Table 



File Type 1 

IFFI • 

GIF • 

IMG • 

PCX • 

MacPaint • 

PiCT • 

TIFF • 



Bitplanes Supported 
2 3 4 5 6 7 8 9 12 )6 24 32 



Compression 


Pixel 




Methods 


Size 


Comments 


RLE 


No 


Use on the Amiga 


LZW 


No 


Widely Accepted 


RLE 


Ves 


B&W Scans 


RLE 


No 


For PC Compatibility 


RLE 


No 


Source of Images 


RLE 


ves 


For MAC Compatibility 


LZW.RLE 


Yes 


Format of Choice 


CCIT Group 3 







With the Introduction of color Macintoshes, a better solution 
was needed, and PICT 2 wax bom. PICT 2 is an extended version of 
PICT, bui is designed to serve the same purpose With the new \ 
came support for color bitmaps linages frorn 1 to 32 bits can now be 
stored in the PK I 2 formal Much like the PCX format, HC1 limit. 
\ our choices ot bitmap depth to 1 . 2, 4. 8, 16 and 32 planes. Notice, 
thai each of thes.- is a number that fits quite well into a byte or multiple 
of bytes. In the case of the Ih- and 32-bft files, the "extra bits" (1 and 8 
respectively) .ire used ,is .in Alpha channel. An Alpha channel is used 
IO Store OXtn information pertinent loeach pixel, like transparency, 
that is not directly related u< itsiolor 

The version ot Rl F compression used in this (ormat is 
reasonabh good and is always applied, making tor manageable 
Hies, As. i 2-i-hn color standard, I'K t 2 is really only of use on the 
Macintosh lis most notable features are thai it ston-s Alpha channel 
data and contains pixel size Information. There ate Minn- very 
Interesting >2 hit color Hies in this format, bul certainly not as many 
as then- are MacPaint files, In general the only reason to heavily 

support this form.it is to easily exchange imam's 
with the Macintosh 

I II I • i;mue«l Imiiiio rile 
frornuit 

While the formats have been reviewed 

in alphabetical order, the best 
has definitely been saved lor 
the last IHT is the most 
comprehensive, and a i 
complex, bitmapped file 
this article covers UH . like 
dard. is designed io he 

■ >f (he FORM/CHUNK 
used by IFF, TIFF relies on 
up the header o( the tile A 
made up of a lag number, 
data Hpe number, data count, and data offset pointer The tag number 
is a distinct, registered number that identifies the tag. The field type 

the kirnioi data referenced by ihe lag. The count is (he number 
of times that the indicated data type will be repeated. The offset t- ,i 
pointer into the hody of the hie, where the d.ita referenced by Ihe tag is 
located. In cases where the data is small, it will be stored in the ofl 
pointer This makes the many two-byte ta>;s eftic lent 

Bec.iuse.it the structure oi tin- lag, again like IFF, it Is easj to 
skip over those tags thai you do not understand Several of the tags 




formal that 

the III st.m 
expanded In- 
metaphor 
tags that make 
TIFF tag .s 



such as Artist. DatcTime, Host Compulcr, Software. Make, and Model 
h.ne no bearing ^n the Image at .ill the tags just mentioned are very 
useful, however, when you are having a problem As ,i de\ eloper you 
can look at a file and determine who and what created it. Often this 
can be instrumental in solving any problems you may have with the 
file The rag-based system also allows a program to support TIFT to the 
degree that makes sense tor it It the program Stores monochrome 
■cans, then Ihe many tags concerning color are unnecessary Vet. 
though the program may support a only traction of the lags m the 
formal, it is slill a valid hie In most cases you have to Support all 
aspects of a torm.it to support any o( it 

The difficulty of TIFF is being a comprehensive reader Since 
there are so many tags, and so man v ways to Store and interpret the 
data in a file, a reader can be quite complex. Adding to the complexity 
is |he tact the TIFF currently supports at least three different cor 
sion schemes in addition lo no compression at all Ihe 1 /W compres- 
sion can also be sub|ect lo a predictor. Ihe standard is equally 
complete In Ihe kinds of pictures it handles: B & W, grayscale, palette 
and true color It e\en has ,i tag for the all-important pixel stCC 

If you are serious about tran sfe r rin g files between many 
different platforms, this is as close as you can come to a universal 
format. Because of the complexity of the format, I would recommend 
testing it f.ir more extensively than you would test any other such 
capability, 

From Here 

There are of course manv other bitmap graphic formats I he 
■even formats discussed in this article were chosen because the) are 
widely used as a method of exchange in their respective niches or 
platforms. Other formats range from the practical, Targa. to theoul-of- 
dale. Degas. One of Ihe formats discussed above will more than likely 
meet your needs. The information in this article is msutti.ient to write 
any sort of file handler, that was never the intent If there is Interest In 
code-level discussions ol these formats, this publication is a goixl 
venue lor such articles. In the meantime, lisled below are sources of 
information for Ihe formats discussed above Good luck In dealing 
with the outside world 



H 



Please write to 

Dan Weiss 

c/o ACs TECH 

P.O. Box 2140 

Fall River, MA 02722-2140 
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Three of life's essentials: 



Amazing Amiga 

JL Xcomputinc LJ Mr 




uiinc; C/^r 



Amazing Computing For The Commodore Amiga is dedicated to Amiga 
users who want to do more with their Amigas. From Amiga beginners to 
advanced Amiga hardware hackers. AC consistently offers articles, 
reviews, hints, and insights into the expanding capabilities of the Amiga. 
Amazing Computing is always in touch with the latest new products and 
new achievements for the Commodore Amiga. Whether it is an interest 
in Video production, programming, business, productivity, or just great 
games, AC presents the finest the Amiga has to offer. For exciting Amiga 
information in a clear and informative style, there is no better value than 
Amazing Computing . 



■ AC TECH^miga 



AC'S TECH For The Commodore Amiga is the first disk-based technical 
magazine for the Amiga, and it remains the best. Each issue explores the 
Amiga in an in-depth manner unavailable anywhere else. From hard- 
ware articles to programming techniques, ACs TECHls a fundamental 
resource for every Amiga user who wants to understand the Amiga and 
improve its performance. ACs TECH offers its readers an expanding 
reference of Amiga technical knowledge. If you are constantly chal- 
lenged by the possibilities of the world s most adaptable computer, read 
the publication that delivers the best in technical insight, ACs TECH For 
The Commodore Amiga. 



AC GUIDE Amiga 






ACs GUIDE is a complete collection of products and services available 
for your Amiga. No Amiga owner should be without ACs GUIDE. More 
valuable than the telephone book, ACs GUIDE has complete listings of 
products, services, vendor information, user s groups and public domain 
programs. Don t go another day without ACs GUIDE} 



100% of the recommended daily 
allowance of Amiga information. 

1-800-345-3360 



Transformer 



by Laura M. Morrison 



I ransfomw makes il easy to use changes of size and angle 
in your Amiga Graphic*. Unlike pain! programs which use hrushes 
and rubber-band boxes (or re-sizing and rotating. Transformer works 
on images II will accept ->nd work on, an image up to 1024 x 1024. and 
net it balk as Paint programs may al the size o( the brush, or require 
you to execute the action "blind" with only the outline of the rectangu- 
lar brush showing. Because Transformi-r t.ik.s iIn sizing information 
from Mi ASCII file, and not from a transient rubber-band box, it can 
scale a sequence of images by exactly the same amount and rotate 
images in end angle. It rotates without distorting the image. Except 
lor II \\1 images il reproduces an image's palette exactly. 

Transformer reads an image, transforms it according lo your 
instructions, and saves the new image. The program gets its instruc- 
tions by reading an ASCII parameter file, called 'transparams' which 
you can prepare using 'ed ' In this parameter file you describe exactly 
how the image is to be transformed by providing: 

1. The depth, width, and height of the input image to be trans- 
formed. If otherwise unknown, this information can be obtained by 
running 'view 1 on the image. The depth, width, and height should be 
input as integers 

2. Translation amounts along the x-axis and y-axis. Use 0.0 and 0.0 if 

no translation is desired You can use translation to ensure that the 
transformed image plots on the screen. Although the translation 
amounts refer to pixels, they must be input as floating point numbers. 

3. Scale factors for the x-axis and y-axis. Use 1.0 and 1.0 if there is to 
be no change of size. The scale factors can be floating point, even for 
nu reasing size I ransformer increases without making an image 
coarse, leaving any filling in. if necessary, to the artist. 

4. Angle of rotation in radians. This may be any angle from to 360 
degrees. (360 degrees = 2*3.1418.. radians.) Rotation is about a line 
perpendicular to the screen at the fixed point and goes counter- 
clockwise The angle is a floating point number. 

5. A fixed point of the transformations. Pick a point that ensures the 
transformed image will plot on the screen. It can be an estimate, or a 
paint program will give you exact coordinates. The fixed punt is 
relative- to tin- input image and not the screen. Note that although the 
fixed point refers to pixels, it should be input as a floating point 
number. 

6. Number of rotations to do (integer) and the angle increment in 
radians (floating point). Transformer will do a sequence of rotations of 
angles increasing by the increment. It saves each image as it goes. 

Illustration (a) is the Migraph scan of the top of a pencil 
drawing Illustration (b) is .1 composite of (a) and two other similarly 
scanned parts of the same drawing. The parts were each scaled 0.57 
and the resulting images combined to produce (b). Illustration (c) is the 
scan (Illustration (al) reduced 0.325. Illustration (d) is the same scan 
reduced b\ il 12S Jn d rotated 1 5704 radians. 



The parameters for the transformations used to produce the 
illustrations, as they appear on the 'transparams' file are 

Illustration (a) 

1 640 600 0.0 0.0 

1.0 1.0 0.0 0.0 0.0 1 0.0 

An image of depth I, width 640, and height 600 is to be reproduced 

without change of size and with no rotation I he fixed point is the 
upper left comer of the screen 

Bottom parts for Illustration (b) (not shown): 
1 640 600 0.0 -200.0 
0.0 0.0 0.0 0.0 0.0 1 0.0 

The scanned image is to be shifted up on the screen 200 rows to give a 
copy of the bottom of the 600 row scan-image. 

Each of the three parts of Illustration (b) (shown reduced and already 
composed): 

1 640 600 0.0 0.0 

0.57 0.S7 0.0 0.0 0.0 1 0.0 

The image is reduced by a scale factor of 0.57 (chosen because it makes 
an image that fits exactly in the screen frame). 

Illustration (c): 

1 640 600 0.0 0.0 

0.325 0.325 0.0 0.0 0.0 1 0.0 

The scanned image is reduced by a scale factor of 0.325. 

Illustration (d): 

1 640 600 100.0 0.0 

0.325 0.325 1.5704 390 188 1 0.0 

The scanned image, reduced by a scale factor of 0.325. is to be shifted 
100 pixels to the right and rotated 90 degrees, that is, 1 .57(14 radians 
Since there is a rotation the Transformer sidesteps the distortion 
introduced by the non-square pixel by first transforming the Image to 
an inches coordinate system, then rotating in terms of inches, and 
finally, transforming back into screen pixel coordinates for plotting on 
screen. X was translated 100 pixels to the right, and the fixed point was 
taken in the middle of the screen, so the resulting image would be well 
onto the screen. Without the shift in \. the head of the image might be 
off the left of the screen. You can guess an approximate fixed point, or 
a paint program can give you exact coordinates. The fixed point 
ensures the transformed image will plot on screen, but does not 
otherwise influence the image. 
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Not illustrated: 

10 400 O.O 0.0 
1.0 1.0 0.0 320.0 200.0 20 0.2 



A high resolution, inter Lice image is to be rotated 2(1 times in incre- 
ments of 2 radian The rotaHon is to be about the tenter of the screen 

I ransformcr kltOWS What variable it il reading by the 
variable's relative position in the input, so it is important to (ill e.u h 
variable position with l dummy value even though that variable will 
not be used. Also, the program requires floating point where it expects 
floating point, and integer where it expec ts integer 

Transformer runs from the C LI and not the WorkBench. To 
run the program enter the C 1 1 and. at the CLI prompt type: 

Transformer . 1 enamc_I or_out put _i mage> 

<inpu: ■ . lenarne* 

In the same directory, besides the tr.mspar.ims file, you will 
need Raw2II BM and II MM2raw. Commodore's public domain 
conversion programs. It you do not have a copy of 'Execute' in vour V" 
directory you will need that also You will also need sufficient disk 
space to write the intermediary raw tile and the final image hie 
Transformer reads the image to be transformed onto a CustomltitMap 
Please be patient as this takes a while because Iransformer first 
converts the input image to raw bitmap iormat using lixeeute and 
II RM2raw Only the upper left part ol this CustomRitMap can be seen 
on screen Facility for scrolling the CustomRitMap has not been 
implemented, but you can gain access to oil -screen parts of the input 
image by translating the off-screen portions onto the screen and 
making an intermediary copy if necessary 



After producing the transformed image Transformer writes 
I raw image tile. then, u-ing Execute and Kaw2ILBM'. converts the 
file to ILBM formal. 

I ransformer keeps a record ol its activity on j file called 
'Run_Nolev' YOU may want to record date and time information here 
.lis,) 

Programming code explanations are included as comments 

in the LISTING 

Iranstormercanbe used lor a variet] of Sizeand rotation 
trail-formations Because ol its repeatability and precision il works 
well with images scanned in part-, and then combined. It makes 
shrinking spin-outs fasl and easy You can draw all your animation 
figures the same si/e. then, to make them recede m the distance, shrink 
them methodically smaller and smaller 

Although it is configured for transforming high resolution 
interlace images, you can change the resolution by changing WIDTH 
and HEIGHT (and the input and output file conversion information) 
and compile versions [Of each resolution you use 1 or example, to 

convert to low resolution 'hi i 'and 'hi r must be changed to 1o5' and 

lo V (\ote the spate m the second string ) You will want to increase 
the precision n \ ^u wish to use the program for technical or engineer- 
ing application- 
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LISTING - Transformers 



termor .c 
■ L-i ■.:■! H- 



' 



• - * 
• 

• include "in' 

■ Include 'ex. 

-de -math. t* 
•define WIDTH 
•define HEIGHT 400L 
USHORTcmapIUl; 
SHORT "cols; 

extern atruct Ra»t Port "rpl; 
extern struct RastPoi ■ ■ 
extern struct Screen 'Opeagci — 

■ truct FileHandl-- ■ 
," Set up lnfon--v - ui-d 
Leave DEPTH 
from the 'transparan 
struct NewScrr>t-r ■ ■ 

D.D.Miirm.wafT 

■ 

STOHBITHAr". 



-hen opening the screens. 
in later when 'indepth' Is read 



-0,1, 



■ Converting input image to raw format . . .-, 
NULL.:: 






4..Q.1. 



"Base; 



V t 



■ 
struct BitHep *l 
struct BitHap 'bitm2j 
struct RastPort "rpl; 
■truct RastPort "tpi; 
struct Viewport • 
struct viewpor' 'vp2: 
struct Intuit. *.mmm* *l 
struct Gfxl' i 
Static float xo, yg. h( 
static float xf. yf. exf 
static float xrx. yrx. xo. yo, tu 
static float xry. yty, 
static float x. 

Static float xxa, yyo. xxt. yyt; 
static float ra. cosza. »inza; 
static float facx. facy, d»] 
static float u, v. uo. vo. xinch. yinch; 
■tat ic char outfi let 120); 
static char gopic 1 120] i 
static char gore* 1 120] : 
static char strl80)( 
static cp . 
static 

static char de.! . 
matntargc, I 
lnt argc; 
char "argvl J ; 
( 

LONG ofh, bf h; 

LONG nextx. ne» 

mt row, col. ci bar, maxrot; 

•fopenn . 'pp. 'lp; 

LONG nb. success, colorslre. numcoln. planeslze.- 

LONG indepth. inhelght. inwidth; 
if (argc < ) i 



print f l* CLI Usage: Need name (or transformed 'l ; 

printf (-output image and name of input imageVn'); 

print f (* on the command line.\n'l : 

exit (10) ; 
I 

IntuitionBase ■ (struct Intuit lonBase "| 
OpenLibraryi 'intuition. library', 0); 
if (IntuitionBaae ■■NULL) 
I 

print* 1 -Couldn't open Intuition library\n->; 

exit tl 0); 
I 

CfxBase - (struct GfxBase •) 
OpenLibrary ( -graphics . 1 ibrary '. 0) ; 
if (GfxHese ■■ NULL) 
( 

printf ('Couldn't openGraphlco Iibrary\n")i 

CloseLibraryl Intuit lonBasel .- 

exit 1 10); 
I 

print f I *\n\n\n\n\n*n\n\n\n' ) : 
printf (• 

print [ I ' TRANSFORMER PROCRAH\n\n- I ; 
printfC •). 

printf ( 'Copyright 1992 by Laura H.'i ; 
print f(" Horrlson\n\n\n*} j 
printf I '\n\n\n\n\n\n\n\n\n\n\n-) ; 
Delay (100); 

if llpp» fopenctransparams-.-r') ) ■■ NULL! 
( 

printf (• Need a parameter file. •transparamB 1 , with\n-> ; 
printf (• depth, width, height of the input lmage;\nl; 
print !( * x and y translation amounts; vn ) : 
pnntt c x and y scale factors; \n' I ; 
print f i* the angle of rotation in radians, 
printf (• coordinates of the fixed point; \n" i ; 
print f (• the number of times to rotate*) ; 
printf (■ and the angle increment between rot at ions.\n') ; 
CloseLibrarylGfxBasel ; 
CloseLibrary ( Intuit tonBase) ; 
■Kit (101] 
) 

/* Keep a copy of the following scanfs on the •trBnaparamB' file 
for reference. •/ 

facanf ipp,- lid lid I Id -.4 indepth, fc inwidth, fcinheight ) .- 
fscanf Ipp. ' \! \l M If '.fcxxt.fcyyt.ixxB.tyys) ; 
fscanflpp.' If ir %( -, tia. fcxf. iyf); 
fscantlpp,* Id If If -.tmaxrot, fcdelza ); 
fclose(pp): 

/' Since the input is on a permanent file and less likely to be 
in error than if keyed in, only this data check is included. •/ 
if Ida < 0.0)1 I (za > 6.2836)1 
I 

printf (• Need angle of rotation •■0.0 and <> 6.2BJ6 
radians. \n')i 

CloseLibrary (GfxBaae) ; 

CloseLibrary (IntuitionBase); 

exit (10)1 
) 

/• An exponential function may not be provided for C •/ 
numcola ■ 1; 

for I i ■ 0j i * Indepth ; i-.) 



numcols ■ 2'numcols; 



coloroize ■ 2'numcols; 

'* Set up a CustomBitKap and its screen for the input image. 

Allocate memory for the structure and bitmap planes, initialize 

the structure, attach the bitmap to the screen and open the 

screen."/ 

planeaize> (inwidth'B) -inhelghti 

bitml ■ (struct BitHap •) 

AllocHem(Bizeof lotruct BitKapl ,MEHF_CHIPJ ; 
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Technical Writers 
Hardware Technicians 
Programmers 
Amiga Enthusiasts 



Do you work your Amiga to its limits? Do you do create your own pro- 
grams and utilities? Are you a master of any of the programming lan- 
guages available for the Amiga? Do you often find yourself reworking a 
piece of hardware or software to your own specifications? 

If you answered yes to any of those questions, then you belong writing 
for AC'S TECH! 

AC'S TECH for the Commodore Amiga is the only Amiga-based technical 
magazing available! We are constantly looking for new authors and fresh 
ideas to complement the magazine as it grows in a rapidly expanding 
technical market. 

Share your ideas, your knowledge, and your creations with the rest of the 
Amiga technical community — become an ACs TECH author. 

For more information, call or write: 

ACs TECH 

P.O. Box 2140 

Fall River, MA 02722-2140 



1-800-345-3360 



.bit ml ••NULL) 

print f ( -No memory lor bitmap str uct . \n*); 

goto quit ; 

) 

Ltwidtb.lnhtlght)) 

(or i . 
| 

■ '-■.. ■ ..■■ • 
A.. 

■Plenes|i| ■■ HULL) 
< 



Bice 



■ r bitmap. \n* I ; 



irol i ] .planeaire. li 



new»crl .Depth ■ indepth; 

nevscrl .CustomBitKap • bttml : 

aerl > intiuct Screen •tOpenScreenUnewscrl) ; 

if iBCrl-.NULL) 

< 

■ f cscrl was null \n').- 

goto quit; 

) 
rpl i tflcrl --Pas: Port ; 
vpl . fcscrl-.YiewPort j 

/• Convert the input file to raw format. •/ 
St rcpy I goraw. *ilbn2n 
)orav.argv[2|)l 
success • Execute (goraw. 0. 0) ; 

lrisuccesf-MULL) 

I 

" Wouldn't convert input image !ile. Vn'l ; 

goto qu 1 1 : 

•*• image tile and road it onto the bitmap. */ 

.e.argvUll; 

■ 

stic,i>. t inf t !•*. It 

I*,H0OCj0UN 
ibfh .. NOT 
( 

tl i 'Can't open image input Iile.\n*> ; 
goto quit i 

lor I l >0 ; i * indeptfi. . • ■ 

( 

.i i«»[i] .planesizel; 

) 
cols ' icmap(O) j 
nb » Read(bfh.cola,calorsize} t 
Close : • 

LoedRGB* I vpl . cmap. 16); 

/• Delete the raw version ot the input file. •/ 
■trcpy<dolf lie. 'delete *); 
■treat (delf ile.argv|2| >; 
•treat (del die. '.hi" I ; 
atrcot (del!: .■ 

success ■ Bx< , ;*. 0.0) ; 

/• Set up a CustomBitHap and screen for the output ima;. 
mi « (struct BitMap •)AllocKem<sizeof(struct 
BltKap>,KO»_ - I 



I 

print! ("No memory for bi( 

goto quit j 

I 



ip struct. \n") ; 



InitBitHap(bitm2. indepth. WIDTH. HEICKT); 
planeaize - (WIDTH/B) "HEIGHT; 
i 0; 1 < indepth; i**\ 
I 



bltm2-»Plenes[l) 
Alloc RastsrlWIDTH, HEIGHT); 



■ 



if (bitmJ->Pl«nea|il ..NULL) 

I 

print! Cbltmap2 planes were null \n') ; 

goto quit: 

) 
BltClear(bitm2->I>lanes|iJ.pl«ncsize,l); 



newscr2. Depth • Indepth; 
newacr2. CustomBitHap -bitm2; 
acr2 « (struct Screen *)0penScreen(*newscr2l ; 
if (scr2«-NULLt 



( 



1 . 



print! Cscr2 was null\n* 

goto quit: 
I 
rp2 . tscr2->rUsiPort; 
vp2 . iscr2->ViewPort; 
LoadRGB4(vp2.cmap. 16); 
numberaO; 

/• Open an ASCII file to collect data on program activity. •> 
lp • fopen(*Bun_Notea". "a"); 

'• 'xinch' Is Inches per pixel horizontally; 'yinch- is inches per 
pixel vertically. Values are based on 4/J width/height screen 
aspect ratio. •/ 
xinch ■ 0.0125: 
yinch ■ 0.015; 

/• Multiply by 100 to enhance calculation precision.. • 
facx • 100.0'xinch; 
facy • 100.0'yineh; 

/• The fixed point after translation, in pixels. •/ 
xo - xf • xxt : 
yo - yf . yytj 

f The fixed point in inches. •/ 
uo » facx'xo; 
vo - facy'yo; 

/• Save recalculating this constant . •/ 
exf ■ xf"(l-xxs); 
cyf . yf(l-yys): 

reewenu 
number ••] 

SetlUst(rp2.0): 

'" Evaluate these only once for each angle rotated. V 

cosza . cos(za); 

sinta ■ sin(za) ; 

for (row ■ 0; row < lnheight: row--) 

1 

fortcol - Oi col < inwidthi col--) 

< 

cc ■ PeadPixel irpl.col. row) ; 
/• Ignore pixels of background color. •/ 

if (cc !- 0) 

I 



l,on 





x ■ If loat) col; 




y > (f loat ) row; 


Scale V 






11 I i.xb !• 1.0) II 

I 

XB " x'xxs • exf; 






ys ■ y'yys . cyf; 




X ■ XB; 




v » ys; 




) 


Translate •! 






ifKxxtHHyytl) 
1 

Xt ■ X • XXt ; 






yc ■ y . yyt; 




X • xt; 




y . yt; 
) 



■• RoEetfl 



/" u end v 



if (za) 
( 
the point in inches coordinate system, */ 
u • faex'x; 
v • facy'y; 
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/• Rotate in inches coordinate to preserve measurements and avoid 
the distort ion introduced by non- square pixels. */ 

xr ■ uo • (u - uot'cosza * Iv-vo) 'sinza; 
yr . vo . (v - vol'cosza - (u-uo)'sinza; 
/" Translate back to pixels coordinates for plotting on the screen. 
•/ 

X ■ xr/facx; 
y ■ yr/facy; 
) 

nextx > (LONCtx; 
nexty - I LONG) y: 
SetAPen(rp2,cc) ; 

if < tn*xlx>Olfcfc(noxtx<WIDTH)ttlnoxty>0)fci.(n«Xty<HEIGHT)) 

( 

writePixel(rp2, nextx, nexty) j 

) 

) /• end or cc not zero loop "/ 

) /* end of col loop */ 

) /" end of row loop V 
■" Finished with this rotation now write an output image. ■/ 
finish;; 

/• Number the output images so they don't overwrite one another, 
"/ 

itoal number, str); 
Sot APen( rp2.lt j 
Hove<rp2.30.30); 
Text (rp2,str.strlen(strl |j 
strcpyloutf ile.argvd ) |j 
•treat (out file. str) : 
Ofh . 0p#n(OUtf ile.HODE_NEWFILE> ; 
if (Ofh !- NULL) 
( 

(or < i » 0; I < ir.depth: !••) 

( 

nb* Write (ofh. biun2->Plones[ i] .planesiie) ; 

1 

cols • tcmepIO); 

nb • Write (of h. cols. colorsize); 

CIoMtofh) j 
I 

Delay<20); 

strcpy (gopic, "raw2llbm *); 
strcat (gopic. outf lie) ; 
strcat (gopic, ' "I : 
strcat (gopic. outf lie) f 
strcat (gopic, * .pic hi •) ; 
strcat (gopic. st rl); 
success - Execute (gopic. 0.0); 
•trcpyldelf lie. "delete •); 
strcat (del file. out file) ; 
Success ■ Execute (de If lie. 0.0) : 

fprintf (lp.*\n Is ta Is '. argv(0|. argvfl] . outf tie) ; 
fprintfUp.' Is \n ',argvt2| ); 

tprintfllp.- lid %ld «ld Vn'.indepth.inwidth.inheight); 
I4.2f %4.2f *.xxt, yyt); 
14. U »4.Jf *.xxs. yys); 
%3.«f *.ze); 

%4.0f %4.0f \n -. xf. yt); 
facx ■ %4.4f facy . 14. 4f '.facx, facy); 



fprintf lip. • 

fprintf Up. * 

fprintf < lp. * 

fprintf Up, * 

fprintf I lp, 

za ■ za • delza; 

'* If more rotations are required go back and start over. •/ 

If ( (za < 6. 3 lit (number < max rot ) > 

I 

goto rotemore; 

I 
qu i t ; ; 

/• Now close files, screens and release bitmap mem* 
lfllpl fclosedp); 
if iscrl) CloseScreentacrlli 
for I i ■ Oi i < indepth; i**) 
( 

if i bitml->plan«sli)) 

I 

PreeRaster(bitsil->PlaneBlil, WIDTH. HEIGHT), 



ry. •/ 



I 



if if 

I 

FreeMemlbitml.sizeol (struct Bit Kap) (; 

I 

It Iscr2) CloseScreen(scr2); 

for 1 i ■ 0: i < indepth: 

I 

:t i bitm2-*Pl«nes(i(l 

( 

PreeRaster I 

> 
I 

if (bitn2) 
( 
rre«He»(blt»i2.Bizeof (struct 

I'.uitionBase) 

CloseLlbrary ( Intu 1 1 
if (Gf xBase) 

CloseLibrarylGfx&asei t 
I / • end o : 

/' itoa is from Kermghan and Rl 
lUafAt.Kr) 
char str | ] : 
int nt; 
< 

C, J. i, oign; 
i f li sign ■ nt I < 0) 

nt ■ -nt; 
i.0; 
do ( 

Stli ; ■ • : • • . 

) while lint /■ 10) > 0); 
-..ign < 0) 
strli..) 
strli) * *\0'i 
for I i»0. 



C . Strli!; 

■itrljj; 
strlj) - c: 



rctur: 







Please write to: 

Laura M. Morrison 

c/o AC'S TECH 

P.O. Box 2140 

Fall River, MA 02722-2140 
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Amazing Computing provides its readers with: 
In-depth reviews and tutorials 
Informative columns 

Latest announcements as soon as they are released 
Worldwide Amiga Trade Show coverage 
Programming Tips and tutorials 
Hardware Projects 
The latest non-commercial software 



Order a SuperSub and get this great Amiga peripheral 




AC's GUIDE is recognized as the world's best authority on Amiga 
products and services. Amiga Dealers swear by this volume as their bible for 
Amiga information. With complete listings of every software product, hard- 
ware product, service, vendor, and even user groups, AC's GUIDE is the one 
source for everything in the Amiga market. 

AC's GUIDE also includes a directory of Freely Redistributable Software 
from the Fred Fish Collection and others. For Commodore executives, Amiga 
dealers, Amiga developers, and Amiga users everywhere, there is no better 
reference for the Commodore Amiga than ACs GUIDE to the Commodore 
Amiga. 

12 Issues of Amazing + 2 AC's GUIDEs! 



A Great Reason to Get Into Your Amiga 




AC'S TECH offers these great benefits: 

The only disk-based Amiga technical magazine 

Hardware projects 

Software tutorials 

Interesting and insightful techniques and programs 

Complete listings on disk 

Amiga beginner and developer topics 



Call NOW for more information 

about these great Amiga 

accessories from 

Amazing Computing! 

1-800-345-3360 



Programming the Amiga in 

Assembly Language: 



In this article I'll t.ilk .lixiul double precision floating-point 
numbers, use them to draw tlu- Julia sel, and start you o(f with some 
elementary menus. There's also a little surprise that will let you scroll 
within the )ulia set All this is in preparation (or the next article when 
we'll use a (aster method (or depicting the Mandelbrot /Julia sets, use 
(ull fledged menus and a zoom routine. First things first, though 

l)Ol RLE PRECISION 

A few articles ago in Part II of this sen.-. (April 1992) I talked 
about single precision numbers and we worked a little with them. But 
their accuracy ts limited, and many programs such as drawing (ractals 
require much more precision. Double precision (DP) numbers use M 
hits to express a number The lett-most bit (63) is the sign (0=posUive. 
1- negative), the next 1 1 bits are the exponent, and the remaining 52 
bits arc the mantissa. This is the reverse order of single precision 
numbers 

The number to be converted to DP must first be written U a 
power of two. Ten, for example. Is 1010; now make this a number less 
than one by moving the decimal four places to the led, or .1010*2*4. In 
DP however, since the first number on the left must always be a 1 , it is 
assumed to be there, is ignored and dropped. So 10 is actually written 
as .010*2*3. The exponent is derived by adding S3FF to the original 
exponent - in this case 3; so the full exponent is $402 

The mantissa is derived be ignoring the decimal and writing 
the number as a 52 bit number adding zeros if necessary. Our mantis 
m this example is 01000000... or $40... and the (ull number is then 
(S40)(24M00)(00M00)(00K00K00). If this had been a negative number, 
add $80 to the exponent. The only exception to this procedure is - it's 
always 64 zeros. 

U'l'slty one more example of 2 5. This ^written as 10.1 and 
normalized to. 101*2*2 and in DP as .01*2*1. The exponent is $3FF.l 
or $400, the mantissa is 01000000... or $40... The entire number then is 
$4UW000000000000. 

Unfortunately, to get this accuracy we must sacrifice 
something and that's speed Since each DP number is 64 bits il takes 
two registers to hold one number. Most basic math procedures involve 
two numbers so it lakes (our registers, for example, just to add. The 
library that handles all basic DP math is ma l hieeedoubbas. library. It 
has the same offsets for it's functions as the math f (p. library (see Table 
I). Most of it's routines require that you put the drst number In 
registers d0,dl and the second number in registers d2/d3. 

DPMATHMACROS.I 

The DP routines are in Listing 1. DPMATHMACROS.i; they 
(ollow the general procedures of SPMATHMACROS t from Part II 
Most of the macros are longer, however, since you might need to 
include two parameters for adding, subtracting, etc. The second half of 
a number is always slored one long word alter the first half, so it's 



location can always be referenced by adding "-4" after the parameter 
For example, if the value in AA is the first parameter passed the 
second half of AA isin"\l*4". 

The macros for sign, cosine, square root, etc. have the same 
offsets as those in the mathtrans. library. Agam, most macros allow you 
to assume or define the second half of the label you're using. These DP 
functions are in the mathieeedoubtrans. library. Both libraries and the 
macro File are included on the magazine disk. 

Since many of the DP math operations involve moving 
double long words 1 tried to write the MOVEDP macro to handle the 
most common cases - data registers to data registers, labels to labels, 
labels to data registers, and dO/dl to a label. Notice the extensive use 
o( the command MEXFT to quit the macro. 

Now we'll use DP numbers to explore the Julia s,t \amed 
(or French mathematician Gaston Julia, the Julia set reiterates a 
function over and over again until it either remains stable or explodes 
out to infinity. The length of time it takes to do this is color coded and 
is the most interesting part of the displav 

The longest routine in the program. CONVKRTDP, will 
convert an ASCII string number to it's DP equivalent. This routine is 
similar to the one in SPMATHMACROS.i, but in case you've forgotten 
how it works. I'll review the DP convert routine. The general proce- 
dure is to - 

1) determine the sign value and save it as or lr$80 

2) convert the number to a whole number times 10 to a 
power 

3) use DPFLT to convert this number to a DP number 

4) divide the DP number by 10 to the power 

For example, .12345 is 12345*10*5 so 12345 would be converted to DP 
format. Once in dO/dl it would be divided by 10 five times The 
routine is heavily commented so try following through it with your 
own example. The two major considerations arc to watch where the 
decimal is and don't try to convert a - just make it 64 zeros. 

ASCII TO l)Ot BLE PRECISION 

In the Julia set all of our numbers will be between -2 and *2 
M we'll have, at the most, only one whole number. The rest of the 
digits can go to precision in the decimal - 1 allowed for up to 15 spaces 
after the decimal. Since the routine to convert a string number to DP is 
so long and only used at the beginning of the program, I made il a sub- 
routine instead of a macro. There is nothing wrong however with 
making it a macro, but it will be repeated everywhere in the program 
where it's called. In this routine i.-^ister .lsM^nmentsare: 



d4 = sign d? < 

aO > decimal scring 



• of digits right of decimal 
a2 = decimal flag 
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Part V - Dinner With Julia 



by William P. Nee 



Register aO contains the location of the decimal String. 1* the 
first chancier value there is a rnintn ilgn then bit 3] of M H let The 

phrase "'-' means to look (or the ASCII value for that character; not all 
ot us can remember these values, but the assembler knows what we 
want. Then check to see if there is a decimal, if there is. flag a2 and 
clear d7. Now each successive character is checked to see if it's 
between and 1. If it is. the contents of dO/dl are multiplied by 10 and 
the cunvnt digit added. The registers are multiplied by 10 using shifts. 
One left shift multiplies by two and the result is stored in d2/d3; three 
more left shifts multiplies by eight and then dO/dl and d2/d.1 are 
added giving the same result as multiplying by 10. The ROX command 
means to rotate and include the carry value from the previous ASL. 
rtus conveniently shifts double regisii-rs Register d7 keeps track of the 
number of characters to the right of the decimal. 

When the entire string has iven checked, first SCC "t ll WW 
lustaO. If so, we're finished since DPOisO. A--summmh.it we have a 
value in dO/dl however, how do we convert that to a DP number' Ihe 
routine DPFLT will only convert the number in dO and we've probably 
got values in both dOand dl for precision 



The maximum exponent in this convert routine is "SJ3F, so 
put that in d6. Keep doubling the value in dO/dl with left shifts and 
keep decreasing the exponent by subtracting 1. When there is finally a 
carry (dO has rotated a value outside it's register] we have the 
number's exponent in dr. and mantissa in dO/dl. This corresponds to 
dropping that understood T I talked about earlier Die mantissa, 

t er, is all the way to the left so we need to move it 12 bits to the 
right to make room lor the exponent and sign. The exponent is in the 
lower halt of d6, so a SWAP will reverse the high and low words 
moving the exponent to the Mi word: four left shifts will then move 
the exponent to the far left of d6 where it can be combined with dO to 
make the complete DP number. 

If a2 is clear then there is no decimal portion to worn' about. 
If it Isn't, however, keep dividing dO/dl by 10 and keep decreasing d7 
until d7 reaches zero. The only procedure left to do is add the sign 
value in d4 to dO. Now dO/dl contains ,i signed, DP number corre- 
sponding to the original decimal string. 




TABLE I 

MATHIEEEDOIBBAS 
I I ACTIONS 



OFFSET 

-30 converts d|>» m dO/dl to a whole ■ in dO 

-36 converts whole ■ in dO to a dp* in dl)/dl 

compares dp*s in dO/dl and d2 

thedpiindO/dl 
makes thedpf in d0/d1 always positive 
-60 multiplies the dp* in dO/dl 

-66 addsthedpesindO/dl andd2/d3; resoil mdO/ 

dl 
DPS! it -72 subtracts the dpt in d2/d3 from dO/dl 

DPMUL -78 multiplies the dp" in dO/dl times d2/d3 

DPDIV -84 divides the dpi indO/dl byd2/d3 



NAME 

DPFK 

DPI I I 

D1VMP 

DPTST 

DPABS 

DPNEG 

DI'ADD 



M ATHIEEEDOrBTRANS FUNCTIONS 

arctangent ol dp" in dO/dl 
-36 sine of dp" in d 

DPCO eofdp#ind0/d1 

tangent of dp# m dO/dl 
DPSB* ineind0/dl . cosine pointer in 

hyperbolic sine in dO/dl 
DPCOS1 1 -66 hyperbolic cosine in d 

hyperbotk langenl indO/dl 
-78 dl (E A <d0/dI» 

DPLOG -K4 natural log otdO/dl 

dp#tnd2/d3tothep >/dl 

DPSQRT -96 square root ol dO/dl 

DI'IIIll 102 convert sp" to dp" 

DPFTfiFJ 108 convert dp* to 

DPASIN -114 eofdpfindO/dl 

120 compute, ifdpflndO/dl 

DPLOG10 -128 compute log, basi- 10, of dp* in dO/dl 
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COMPLEX NUMBERS 

Earlier I said ih.n IuIm m(s were n rep r e sentation oi repeated 
iterations ol a function Since a function with just one unknown would 
produce a straight line we'll use .1 function with two unknowns; the 
Kcond unknown, however, will represent an imaginary number or 1 
(the square rootoJ -1). So any number, call it Z.i> really X-iV.The 
function well keep repeating is Z A 2, or. in other words, new Z*Z A 2. 
The new real part ol Zis X' 2-Y A 2 and the new imaginary pari is 
2"Vi To compute the [ulia Set we'll always add .1 constant value to 
our result - another complex number C composed of .1 real a and 
imaginary U(«r|A*iJB> Now to square our number -N'EWX ■ X*X- 
Y'Y-J'Vand \ i W ^ 2'X"Y+JB 

Anytime the distance 1 of our new point 1- more than 2 units 
long, thai value will eveniualK explode Art easy way ol expressing 
this is "0 X*X+Y*\ -1 avoiding square root computation Hut how 
long do you keep iterating before \>.ni <m> assume a value will never 
reach that condition? riiat depends on your lime and patience. A low 
iteration count (around tO) can produce satisfactory results for low- 
wale pictures It may take an iteration count of 1000 for very high-scale 
pictures 

All of the Julia Set is within a box -2 to .2 in both the X and 

Y directions (theZ value), the constant C you pick cart be anywhere 

inside that box (a - -II' will produce the same result). If you want to 
enlarge erne portion ol the display, change the X and V values but keep 
c die same rolook at just the upper one-quarter, X could go from -2 
to and Y could go from to 2 The scale for X and Y is the distance (or 
each divided by the size of the display Points that tall within the Julia 
Set ire ill colored the same (usually black); all of the rest are colored 
by establishing a color relationship to tin- iteration count Phe entire 
process can be computed as 



rXRIGJ ■ :■. . 
YBOTTT*U - 2 : YTOP= • 2 : YSCAU 
FORK=0TV 

FOR V=0 TO 63 :Y=YB0TTOM- VYSCALE 

:ON 

IFASCH-i" . S IaXJP 

" ' ■ 
A'ASv'r 
NEXT C : 

■ ■ 

LISTING 2 

This is the same procedure as I istmg 2. the machine 
language program I've pul several coordinates you might want to try 
at the end of the listing. They all cover the entire Julia set so you may 

want to enlarge them by changing the X and/or Y distance, be sure to 
leave the last two coordinates the same or you'll get a different Julia 

set 

Since there will always be six coordinates to use, the 
"cOnvert_to, DP" routine must be able to read all six of them. Any 
mistake will cause d6to come bade with an error flag and will 
terminate the program. This probably means a value has too main 
digits Space Preserved tor the six variables using DC.L Oat the end of 
the listing 

The most used portion of the program is the inner loop 
where the iterations are carried out After computing Asquare and 
Bscjuare the squares are added and compared to 4; if the value is lower 
the program computes a new real and imaginary value adding J A to 
the real portion and JB to the imaginary portion 







TABLE II 












MENU STRUCTURE (30 bytes) 


MEM) ITEM STKl CUKE (34 bytes) 









pointer to next menu structure or 




long 


pointer to next menu item structure or0 




4 


word 


left edge of menu - relative to 


4 


word 


left edge ol item, relative to menu 








i> -border 


6 


word 


top edge useO for top Item 




6 




ttoO 


8 


word 


width ot menu item 




8 




width of menu 


10 




■ 




10 


word 


menu mN toO 


12 


word 


UIECKiT(Jl) 




12 


word 


■ mi enabled (SI) 






CI (52) 




14 


long 


pointer lo menu name, null-term] 






Q(S4J 




18 


long 


pointer lo first menu item structure 






Ml \l rOGGI 1 




22-28 




USCd by intuition ■ »et 


14 
18 

22 
26 

28 
32 


long 
long 

long 

long 

word 


II NA8I 1 IHS10) 
HIGHIMAGE ($0) 
HICHCOMP(S40) 
HICHBOX(SSO) 

lilt ,ll\ONE (SCO) 
( UK KED(S100) 

mulualexdudc 

Item Mil - pointer to [mage or text 

select till - pointei to image or text 

command ke\ 

padding ■ set toil 

pointer lo SUD-ltl 

next select let toO 
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If the -.mil ol the squares is 1 or more the point i~ outside the 
|uli« set and colored accordingly. I've included (our different color 
routines you could use based on the iteration count - 

■• i . 

- 

■ 

Another method of coloring is to assign a cokx value toeacn possible 

count; this is called .1 'hash'' table It the count was 973, you would just 
t;el the 973rd. value (rum VOW color table and use it 

Any point that never reaches 1 In the end of the iteration 
count is probably within the fuli.t set and is colored with whatever 
color you decide to use Most programs use black but Amiga Palette 1? 
is also a nice choice. There an- even ways tocolor points within the Set, 
but I'll leave thai up tO you to figure OUt I've added a new palette that 
you can use In passing ifs name with the PAI 1 n I macro. 

There are several DP numbers dedarcd as variables near the 
the program Although only a few of them are Used I've 
included them as examples if you want to see how good von are .it 
converting numbers All the "numbers! ring" value* are the locations of 
some fulia Sets von might want to try If you add your own be sure to 
enclose the String with a single quote and follow it with a comma and a 
/ero(\LI I II KMINAITU) When \ouve tvped m the program save 
it as JULIA.ASM. Then assemble A68K JULIA.ASM and Blink 
JUI.1A.O. Run this program from CLI as JULIA; re-assemble and Blink 
whenever you change coordinates or palettes 

SCROLLING 

I said that I have a little surprise tor you You can make your 
screen and window bigger than 320 by 200, drat* ofl the screen, sat e 



the picture and then stroll through it. Sort of like a super-bitmap, but 
without all the hassle Here's how 1 made .1 lores, non-interlaced, 32 
color M0X400 picture Change the coordinate*, of the |ulia set so only 
the bottom one-fourth will show on the screen; 1 used -1 4,0, -1.1.0, - 
W4. <-ri57. Then change the screen and window dimensions lo 
640X400. Kor Coloring, I used a count of 512 and ANDed each count 
with 31, 

Keep the scale the same, hut Increase the K r* >ss d istance to 
640 and the down distance lo 40ll. the rest of the picture will he drawn 
off the screen When it's finished you need to save it I like to use 
PulSaver since it runs in the background and you can save a picture at 
any time (CI Kl 1 At I !i Once you've saved \our picture, show it 
with a program like Super View. With Super View you do need to use 
the -m option since the program thinks that the larger screen is a high- 
resolution picture I used SUPERVIEW -M -XI -W320 -11200 

II 1 I Ai.JEMO Pl\ to show my picture, then you can hold down the left 
mouse burton and scroll around the picture For your convenience, the 
Public Domain programs PiclSaver and SuperView along with their 

docs and |u I ia Demo. Pi x are on the magazine disk 

MKMS 

No dinner is complete without a g<*xl menu from which to 
choose. So let's talk a little about menus subtle, eh' Just as screens and 
windows have a predefined structure SOdO menus Table N lists the 
elements of the menu structure But a menu title is usually meaning- 

ithout SOme items under it These items have their own structure 
called Menultem and again are listed in Table II. In turn, menu items 
may each have their own sub- menu items; fortunatelv their formal is 
the same as menu items. Finally, there must be something to read in 
each menu. Intuition can print null-terminated string text in a menu, 
gadget, alert, etc As you would SUSpeCt, this text must he in a 
structured format; see Table 111 tor the Intut Ie\t structure. 







TABLE III 












ENTUIMESSAGE STRUCTURE 




INTUITEXT STRUCTURE <20 bytes) 








(52 bytes) 


1 


byte 


rrouod pen ■ 
background kground 11 









IMJvfESSACI 






Iam: 




20 


long 


IM.CLASS-IDi 


2 




drawing mode Q AMI, |AM2 




:4 


word 


IM.CODE - menu/itcm/sub-itcm 


3 


h\ te 


padding ■ set toO 








telei ■ 


4 


word 


lelt edge- relaln e to 1 ontamer 




26 


word 


im .QUALIFIER - keyboard Inform 
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ontainer 
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Ion,: 


iv, LADDRESS- address cH intuition 
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long 


font pointer or 








obk 


12 




pointer to null-lerminaled text 
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word 


IM MOUSEX - mouse X coordinate 


16 


long 


■tuitexl - set toQ 
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word 


l\| MOUSEY - mouse- Y coordinate 
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IM.SECONDS- current time 






. 
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IM.M1CROS current time 
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long 


IMSPiClAIM\K-usedln system 











Volume 3, Numbed 1 



37 



Lei's discuss the various flags m the menu structure m moit 
detail Iheonly menu flag is I '\AHI.M)($ll; this means the menu will 
be fully visible ami ready (or use. The flag-, (or a menu j(em are more 
^ tried lo show greater variety The available flags arc: 

CHECKIT (SI ) - an attribute item; can be mutually excluded 

1TEMTEXT(S2) - item will contain ted 

( I >MMSEQ <S4) - there will be a command kev 

MENUTOGCLE (S8) - toggle the checkmark 

I IT M ENABLED ($10) -menu item is initially enabled 

HIUiiMACi (SO)-dnpU user's Image 

rflGHCt IMP <S*>) - highlight by complementing colors 

HIC.HBOX ($80) - draw a box around the selected item 

Hll,ll\0\l (Si i)i . no highlighting 

( IIH KED(SIOO)- this item will be checked 

Another field that needs explaining is mutualct. lude li 
you've flagged a menu item with CHECKIT then it can be used while 
all other options an? excluded. Since you want an attribute item (as 
opposed to an action item Ho only be selected once, you tell Intuition 
to exclude all other attribute items with a 32-bit long word; the I'a In 
this word represent the other menu items to be excluded when this 
menu item is picked. A value of SFFFFFFFE would exclude all other 
menu items when the first one was selected; a value of SI would 
IXW I) s exclude the first Item when any Other item was chosen 

The command field allows you to acCCSS a menu item from 
the key board by pressing nght Amiga plus a key. The ASCII value for 
this key must appear In this field Intuition will add A' and the 
character after the item name, so be sure to leave room for it In the 
same manner, checkmarks are added before the attribute item name so 
also lea\ e room for them. 

ATTACHING MEM S 

Now, how do we attach our menus to a window? The 
Intuition command SelMenuStrip will attach alt menus, items, sub- 
items, and text to your window. Put the window address in register ad 
and the menu address in al. Use the command ClearMenuStrip to 
remove all menus by putting |ust the window address in aO; call this 
function before closing any window with a menu. 

Before we can read which menu, item, or sub-item the user 
has selected we must make sure our window has the proper IDCMP 
flags (see Pari II) needed for menus MENUPICK will let you know it 
the user has released the RMB (nght mouse button) over a menu: 
MOUSEBUTTONS will keep track of mouse X and fnOUSeY coordi- 
nates 

The general procedure to check for a message is to use 
WaltPori to identify the LserPort. uscCetMsgloseeif the user has 
activated a menu, clear window gadget, etc., sort the message into one 
of three categories, and use ReplyMsg to immediateh answer the 
me nag e (see Table III) The three types of me ssages are 

IH. CLASS - the IDCMP Hags 

IH.CODE - menu values 

IH. (QUALIFIER - raw key values 



HEN! .1 

In Listing 3 (MENU.il I've included most of the menu values 
you need I'll talk about some more features of menus in the next 
article, but this is enough to get you started. The three macros open a 
menu strip, evaluate the menunumber, and close a menu strip 

To use all of this information I wrote a short program 
(Uflttng 4) thai uses the W Bench screen and sets up a menu with two 
items Both items are attribute Items with the first one checked, and 
both have command keys. Select an item using the mouse button or 
Amiga M or Amiga I; after selecting an item a short message appears 
for a few seconds. Close the window using the close gadget or by 
pressing ALT/LAMICA. Try using different combinations of menu 
item flags and different pen colors. 

To write the two menu messages, I used a new routine - 
Text. This Is a graphics command that will print text at any location m 
any color. The LOCATE macro positions the pens 1 added a CTEXT 
macro thai require the color, address of the CTEXT, and it's length 
The CTEXT is not null-terminated I've also added a DELAY macro to 
DOSMACROS i; it uses the passed value to call the IX>S (unction 
Delay. Copy or assemble this program as MENU. ASM. lasting 4, 
MEM! I, DOSMACROS i, and CFXMACROS.i are included on this 
disk 

NEXT TIME 

You can see that as you increase the number ol menus, 
items, and sub-items thesourcecodegetsunwiel.lv veryquickh; li\ 
todevelopeyourown macros to handle the repetitive portion of menu 
Creating: next time I'll show you how I did it. In the next article we II 
also use scaled numbers to draw the Mandelbrot set String gadgets to 
input coordinates, and include I zoom routine to enlarge VOUI 
drawings 
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If the IM.CLASS value is the same as the IDCMP flag for closing a 
window, then go to the program routine that closes that window If it's 
the MENUPICK value then a menu has been chosen and we need to 
look at the menunumber value in 1M.CODE to see which menu item 
and sub-item were selected 

The menunumber us a 16-bit value; the right-most five bits 
(4-0) are the menu numbers Starting with menuO, the next s )t bits (10- 
6) are the item numbers starting with itemO; the last five bits (15-11) are 
the sub-items, again -farting with sub-itemO. By using shifts and 
rotates you can mask these three locations and separate their \ alues A 
menunumber value of SFFFF means that no menu item or sub-item has 
been -selected, this is called MINI \l I 1 
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cloaalib dpMth 

ClO«B_0t» 

cloaelib gfx 
cloa«_t.r.t 

cloaalib int 

dona 

taova.l atacK.ap 
rta 

IVMBC 



■tack dc.l 

gl-Mw dc.l 

mtbaaa dc.l 

Opn*ttib**a dc.l 

.uy nwi 

of* dc.b 'grapnica. library'. 

■vajflpc 

inc dc.b -intuition, library'. 

avanpc 

itn dc.b ■auuhtaaodoubbaa. library'. 

mope 



.■'Mtivt atoraga locationa 



vyacraan i 

dc.H 0.0. 12C.I00.daplfi 

dc.b 0.1 

dc.H 
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dc.l 0.0.0.0 

ry-indOM 
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ma dc.l 0.0 

bb dc.l 0.0 
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onafp dc.l SlftOOOOO i first naif only 

tnofp dc.l S400C000Q 
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dc.H SOOO.StOf.SdOf .SbOf.S90f.S70t.SSOf .1401 
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dc.H SOfO.SlfQ.S6fO.S9[C.SbfO.SdfO,SflO.SfaO 
dc.H S'd0.S(cO,Sfa0.St8O.S(S0,St«0.»(20.Jf00 
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Th»- complete set of listing's for 

1 *!■« »:ii-;i niTiii n- the Amigu in Assembly 

Language — Part V can he found on llie AC's 

TK< II <li-k. 



Please write to: 

William P. Nee 

c/o AC's TECH 

P.O. Box 2 1 Ml 

Full Kiver, MA 02722 
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Trading Commodities: 



by Scott Palmaleer 



Introduction - The Story of a Mouse with Three 
Buttons 

I have a three-button mouse Most Amiga applications 
Support only two-button mice. I used to wonder what the middle 
I ' - tor. since although the Amiga's operating system has the 

Capability tO recognize the middle button, nothing happens when it is 
pressed. Then I read about some public domain (I'D) programs that 
cause the Amiga to pretend that the shift ke> is being pressed when 
the user prase* the middle button "Ah. " I thought, "final I v a use lor 
my fancy three-button mouse." Some programs, including Imagine, the 
Workbniih. and undoubtedly others, allow the user to do "multi- 
selects"; th.it is. il the user holds a shdt key down while selecting items 
on the BCfCCn with the left button, all the items, not lust one. become 
selected Masking the middle button press as a shift key press frees the 
user from having to do this multi-selecting with both hands Rush 
obviously very convenient. 

At the same time, programs such as ProWrifC have other 
"key-button" combinations, lor example. In I'roWnte If one holds 
down the .ill key while using the menus to DOefl a file, the file 
requester will displa) all tiles (bra given directory, not nisi ProWrite 
files I have always tnund this a bit aw kward, and so I have always 
wished for a way to let my middle button pose as the alt ke) 

I could easily obtain the I'D program to convert mv middle 
button into a shift ke> , but I could not tmd one to make it into an alt 
key. Besides, even il 1 found one, there is no telling vs hether the two 
would work together. So, I decided to write my own program that 
would let me Control what the middle mouse button did from one 
centra) Interface, guaranteed to work with Itself! Dial is where 
VVorkbi Commodities" comes in. and the result o| my effort 

is MMIt ( Y s mull and limplc-tO-USe commodity that allows the user 
to convert the middle mouse button into a left shilt key, I right shilt 
key. a left alt key. a right alt ke\ . a left Amiga key. a right Amiga key. 
or the control key, MMH lA also prov ides a "hotkey" that brings up a 
window through which the user can control the program. Bv default, 
this "hotkey" is activated by holding down the middle button and 
pressing the help key. but the user can change this to any other 
combination 

A Bit About Input Events on the Amiga 

Normally, when the user causes some kind ot input ta 

kevpiess. a mouse move, etc.). a program .ailed the input.dev ice 
Creates If) input event that is Introduced to the "input stream" 

(Figure 1). The input event is a data structure that contains information 

as to what kind ol event it is foe instance, it also includes 

information like the time of the event and the coordinates ol the mouse 
at the time. i| theevenl Ilie input event then travels down the input 
stream, which is a chain ol programs that are interested In input. Midi 
as Intuition and the console device The input event visits each 
program, or handler, in order The user can install his own "input 
handler" into this input stream, the input handler waits tor certain 



events and acts, upon them when it receives them 1 his action can he 
bringing up I window, blanking the screen or the mouse pointer, or 
lust about anything else But as I mentioned before, it can be difficult to 
get more man one of these handlers to work together 1 ins is where 

Workbench 2 O's Commodities come in 

The Commodities Exchange System 

Workbench 2 s Commodities have nothing to do with 
money, even though brokers and an Exchange are involve.!' It is 
simply a name that the programmers have chosen to refer to this 
System It h< an object oriented approach to standardizing the way the 
user modifies the way input events (ke) presses, button press,-, 
mouse movements, etc ) are handled by the Amiga. And the best thing 
about Commodities i- that they are guaranteed to work with one 
another As I have said, there are numerous I'D programs that modifv 
vents, hut thev all do so in their own isolated way, and 

compatibility problems have occasionally surfaced when using them 

logethei With Workbench 2.U, the user basically only has to inform the 
operating system thai he would like to modify a certain event into 
another, or just monitor the input events lor a certain "hotkev" 
combination, and the commodities library takes .are of everything else 
tor you! if is realty quite eleganl There Is even a function called 
"Hotkey thai creates a hotkev in one fell swoop' To do the same |ob 
without Commodities. I would have had to learn about opening the 
input.dev ice. interrupts, and other complex issues In MMB_CX. I had 
only to tell the system to "listen" for middle button presses, and 
convert them into whatever qualifier key I had chosen at (hat particu- 
lar moment, say a left shut ke) 

How Commodities Work 

The Commodities system installs a custom handler, 
maintained bv the system, into the input stream before Intuition's 
input handler (Figure 2). The fact that Commodities sees, each input 
event before Intuition does Iscnicbtl to their operation II lets the user 
install I commodity that swaps the (unctions ot the left and right 
mouse buttons (tor letl-handed users), as fiu as Intuition is concerned, 
the user ha. done nothing unusual 1 In the example ot MMH C V it 
allows our program to convert any middle mouse button press into a 
left-shift (or whatever) before Intuition realizes it. 

Commodore supplies a control program, called Exchange, 
that allows the user to control the commodities installed in his system. 
This program shows all the Commodities currently running. It can 
temporarily disable/enable any of the commodities, or permanently 
gel rid of them. For those commodities thai have some kind of control 
window to control their individual features, Exchange can instruct 
them to bring up their control window. Exchange can also tell the 
commodity to. lose its window ibut keep running). Exchange ads like 
a commodity itself, once running, its control window can be brought 
up with the hotkev combination of "all-help" 

The user can use the Toollype em ironment of Workbench 
to control certain options for the Commodity, such as priority We will 
discuss this later m more det.nl 
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The Broker 

A commodity is really a collection of "objects' (GcObj'sX one 
of which is a "broker." connected toe,elhei in a particular fashion, and 
Kfencd to m data structure circles as a lav. The broker is ihe central 
reference point tor the entire commodity, and it occupies the root 
position »'( the tree The broker, upon receiving an input event trom 
the input device, converts the event into a commodity message 
(CxMsg) and diverts it to its children (the CxObj's connected to the 
broker). When they are done doing whatever they want to with it, the 
broker sends theGcMsg to its next destination, which can be another 
broker, or the next handler in the input stream (Figure 3), Brokers are 
organized by priority; by setting broker As priority higher than broker 
B'S, you can make sure thai broker A sees the input event before 
broker Bdoes. This can be important when you have more than one 
commodity running at the same time. 

The Filter Object 

There are a variety ol types of CxObj's. One of the most 
important, because it is used in almost even' conceivable commodity, 
is the Filter CxObj. Its lunction is to filler out any unwanted input 
events before passing them along to its children Tor instance, in the 
case of MMB_CX. we are interested only m events thai involve a 
middle mouse button, so we inform the Filter lhal it should lei only 
those events pass by to its children; it the event does not meet (he 
Filler's standards, it is passed to the Filter's siblings (if the Filler has no 
siblings it is passed back to the parent* This prevents our commodity 
from having to do loo much work All CxObfs, including Brokers, pass 
I «Alsg s in this pattern- lirst to any children, then to ^t\y siblings, and 
finally to the parent. 

I should point out a few things before I explain anything 
els.' All of these CxObj's are implemented and maintained by Ihe 
system I do not have to know exactly how they work; I have to know 
only that they do indeed work. This is what I meant when 1 said earlier 
that the Commodities system is an object-oriented system. Construct 
ing a commodity involves little more than assembling ihe appropriate 
ob(ects in the correct way. Ihe details o) their actual operation are 
unimportant. There are enough types i>! objects to let you do just about 
anything you want. 

The Sender Object 

Another type of object is the Sender CxObj lis |nb is lo send 
my commodity a message when it receives a CxMsg from its parent. A 
typical use for Ihe Sender CxObj is to have it connected to a Filter 
CxObj; when the Filler encounters an input event that It likes, it pass,-. 
it down to Ihe Sender. The Sender, upon receiving Ihe message, alerts 
mycommodil riiodiU '.in then take some appropriate action 

Tins is how hotkeys ue implemented In the use ol MMH.CX. a Filter 



looks lot an middle mous.- button - help kev" combination; when it 
finds >-iw. it passes the message lo a Sender, which sends vel another 
message to MMB_CX. which pops open the command window. 

The Sender CxObj sends my commodity a CxMsg containing 
a COPY of the input event that it received, along with an application- 
axle number, supplied by me Ihe fact that the input event is a 
COpy is important It means that Ihe Sender does no modification to the 
input event, and any fiddling we do with it in our commodity 
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Click* 11« on °e»d*> S*-vlc» e*'d 

application will not atfeel the input event .it .ill If we want, there are 
objects thai can change the input event. 

Alter the Sender ha* sent its application a message, it follows 
the typical QtMsg passing pattern. When using Commodities to 
implement a hotkey, the Sender usually has a Translator CxObj (or a 
sibling 

The Translator Object 

The Translator CxObj converts one input event into another, 
or into a string of them. The Traaslator can even "swallow" the input; 
thai is. it can cause the system to pretend that the input event never 
occurred This is wh.it usually follows a Sender in a hotkey applica- 
tion Once the commodity is informed that we have activated our 
hotkey combination, we do not want the input event to continue down 
the input Stream Using ■ Translator CxObj, we simply get rid ot it 

The Translator can also be used to transform an event into a 
string of them. You might USC this feature to convert a function key 
event inlo a string ol characters, or anything else that you find useful 

We cannot use a Translator in MMB_CX, though, because a 
Translator has to be told ahead of time what to use to replace a 
particular input event MMH t \ allows the user to change a middle 
mouse button event into one ol several others Another tvpe of CxObj. 
the Custom CxObj. is ap propr ia te here. 




Figure .i. The path of an input event/Gdlsg through a Cowoditv 
(denoted by the thin curved line). Note that Filter objects 
only pass the Odls? to their children if the CxHss Batches the 
Filter's criteria. Rlso, cone objects can be used to cwletel 
rettove input events fron the strean. 



The Custom Object 

The Custom CxObj i- similar to the Sender ( vOt-jin that it 
informs my commodity upon recei* ins •' ' x\Kg However, the 
Custom CxObj do»~- noi --nil a c x\tsg with a copy of the input event; 
it calk a function, defined by my commodity, with a pointer to the 
actual input event Since the function called by the Custom object 
works with an actual input event, it must Ik* extreme!) larehil. and 
extremely quick. It must also be declared in a special H a) I sine SAS/ 
C, the function should have the Mveds kej word preceding the 
function definition. Irus keyword saves the "global data segment 
pointer." This is ■ technical point which I will not go into here, suffice 
it to say that our Custom (. xObj's function will be called not b) out 
commodity, but indirectly by input devkc It therefore nnnN to run a 
little differently from our other functions. 

In MMB ex, the function requalifyO is called bj a > ustom 
CxObj. RecjualifyO simply takes the middle mouse button qualif) 
of the input event and replaces il wilh whatever we have chosen to 
have the middle button signify, lea ving everything else Intact. It then 
returns control to Commodities 

There are other CxObj types, but MMU ( \ does not use 
them, so I will not discuss them here 

How MMB_CX Is Organized 

Constructing our commodity begins with creating the 
Broker Ihis is done with the following statement: 



broker 
ierrorvariable) ; 



CxBroker t imynewbroker 



where "mynewbroker" is ,m instance of an Initialized \ewBroker 
structure. The WwBroker structure has various PJeJds to tell Com- 
modities how to us*- this commodity, such .is the name ol the commod- 
ity, whether it has a popup control window, etc I he variable 
"errorvariable" is filled m by theCxBrokerO function it there is some 
error creating the Broker The erroi could be lack <>t memory, or the 
fact that another commodity with the same name is already running 
Our Broker has two immediate children, both of them I liter 0* 
The first Filter object is used to "listen" (or our hotkey event; the 
second Is used to listen for middle mouse button events This order is 
important, because remember that our function lequ.ilitvl) removes 
the middle mouse button qualifier from the event and replaces it with 
something els.- It we removed the middle mouse button qualifier 
before our hotkey Filter got to examine the input event, it would never 
acknowledge that our hotkey had taken place! 

The hotkey Filter itself has two children, a Sender and a 
I ranslator. The Sender notifies MMB_CX that the hotkey combination 
has been detected, •imi the 1 ranslator removes the event from the 
input stream. This structure, a Filter wilh a Sender and Translator as 
children, is created in one statement: 

filter = Hotkey(hotkeydesc 

fcrheeeTiotkeydescnption" is a description of the hotkey combination 
we are looking for, "port" is a pointer lo a message port thai We USB lor 
communication with Commodities. ,in,i id is ., special code the 
Sender places bi iheCxMsg mi that we know why we are receiving the 
message. The three objects could be constructed individually, but 
using the Hotkey)) function is easier to understand at a glance 

Description Strings and the InputXpression Structure 
The description for the hotkey is a normal C string consist- 
ing of certain keywords I hese kevwords are used to describe a large 
variety of Input events the string is formatted into lour basic fields: 



[class) 
upstroke] -- ~ , . 



»r I synonym) ( [ | - 
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(the above ■> taken front the Amiga ROM Kernel Reference Manual: 

I ibraries. The square brackets imply thai the option contained within 
is optional, the curly braces indicate that the option within may be 
repeated as many times an desired; the \ ertical bar means "or".) The 
first RekJ, "daw" indicates the general type of input event. It can be 
any of the following 

•rawkey" 

"rawmouse" 

•event ■ 

"pointerpos" 

"timer" 

"newprefs" 

•diskinserted" 

•diskremoved" 

The class names should be fairly self-explanatory. "Rawkey" means a 
keyboard event, and "rawmouse" means a mouse event. If the "class" 
is left out nl the string, "rawkev ' i- assumed. 

The next field is the qualifier field It further classifies and 
Specifies the event from the class level. It can have any of the following 
values 

•lshift" 
■rshifi - 

"caps lock" 

"lalf 

-rait" 

•lcorrmand" 

"rcotrmand" 

"numericpad" 

" repeat " 

:mjtton" 
"r but ton" 

• button" 
"relat ivemouse" 

Preceding the qualifier name by a dash tells Commodities to 
ignore that qualifier. For instance, if we wanted to wait for left-shift 
events, and we did not care whether the user was simultaneously 
holding down the left alt key. our description string would be: 

•rawkey -lalt lshift" 



The last field gets down to the individual key. The "highmap" can be 
any of the following strings: 

"space" 

"backspace" 

■tab" 

"enter* 

"return" 

■esc- 

"del" 

"up", "down", "right", "left" 

'tl", '12' "£10" 

•help- 
So for our example commodity MMB_CX, the default 
description string for our hotkey is: 

•midbutton help" 

which tells the Filter to look for the press of the help key while the 
middle button is being held down. 

We can also specify an " ANSICode" instead of the 
"highmap". The ANSICode is a particular key, derived from the 
current key map For instance, if we want to watch for the press of the 



BROKER i 



FIL1ER 



♦iFILTER 



I 



SENDER — ►IrtWSLftTOR 



Figure 4: The structure of IM.CX, Tkr first fitter is used for 

m hotkey conbinition, ind its first child, the Sender, notifies 
IMB.CXuhen the combination is detected. The filter's second child 
then reaoves the input event fro* the systen. The second filter 
is used to detect niddle Muse button events. Its child, the Custon 
object, oils our function rewalifyt) to convert tie event. 



Notice that mouse buttons are listed above, too. That is because they 
■re valid qualifiers, We can instruct the commodity to wait for mouse 
button events by listing these in our description string. 

The "synonym" section is used to indicate synonyms for the 
qualifier keys, as when the user means both shift keys (or both alt 
keys) I he synonyms accepted are 

"shift" 
"al" ' 
"caps" 

"shift" means to accept either shift key. "alt" means to accepts either 
lit key, and "caps" means to accept either the caps lock key or either of 
the shift keys. As with qualifiers, the synonyms can accept the dash, 
signifying that their meaning -regarded. 

Next, the user can specify "upstroke", in which case only the 
lifting of a key will matter to the Filter If the user specifies "- 
upstroke", both upstrokes and downstrokes arc considered matches by 
the Filter. 



"t" with the control key, our description string is: 

"control a" 

Keep in mind, that depending on the current keymap, the "A" key 
may or may not produce an ASCII "a". 

Another way to describe input events is to use the 
InputXpression structure. It contains fields that correspond to a 
description string, and the commodities. library contains functions to 
convert a description string into an InputXpression structure. I use 
both structures in MMB_CX. 

Using Filter and Custom Objects Together 

Our Broker's second child is another Filter object, with a 
Custom object as its only child. This Filter is the one that waits for 
middle mouse button events When it finds one it sends it down to its 
child, the Custom object, which calls our function, requalify(). 
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ACs TECH Disk 

Volume 3, Number 1 



A few notes before you dive into the disk! 



• You need a working knowledge of the AmigaDOS CLI as most of ihe files on the 
ACs TECH disk arc only accessible from the CLI. 

• In order 10 fii as much information as possible on (he ACs TECH Disk, we archived 
many of ihe files, using ihe freely redisuibulable archive uiiliiy 'lhare' (which is 
provided in ihe C: directory ). lharc archive files have ihe filename extension Izh. 

To unarchive a fikfoo.tji. type lharc xfoo 
For help wiih lharc, lype lharc ? 

Also, filts Kirt 'lock' icons can be unanhived from ihe WorkBtnch b\ doublc-i licking iht icon, and supplying a path. 
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RequalifyO then converts the middle mousebutton qualifier value into, 
say. a left-shift value. The Custom object then regains control from 
requalifyO. and passes the modified event on. Any handler further 
down the input stream will then receive an input event that looks like 
the left-shift key was pressed, but you and I know lhat the middle 
button was really the one that was pressed? 

Communicating with Commodities 

As I said earlier, we have to set up a message port through 
which we receive CxMsg's from our commodity objects. These 
messages can be of two types, CXMJEVENT and CXM_COMMAND. 
CXMJEVENT messages are sent by Sender objects, and 
CXM_COMMAND messages are sent by the Exchange program. Once 
we receive a message at our port, we can determine its type by using 
the CxMsgTypeO function, and we can extract the code number using 
the CxMsglDO function. If we want, we can even extract the copy of 
the input event, using the CxMsgDataO function 

If we received a CXM .COMMAND message from Exchange, 
it can have one of the following CxMsglD's: 

CXCMD_APPEAR 

CXCMD_DI SAPPEAR 

CXCMD_ENABLE 

CXCMD_DISABLE 

CXCMD_KILL 

CXCMD__UNIQUE 

The CXCMD_APPEAR is a request from Exchange that we should 
open our command window. Exchange knows whether or not our 
commodity has a control window, by setting the COF_SHOW_HIDE 
flag in our NewBroker structure. If this flag is not set. Exchange will 
not send this message to our commodity. Similarly, the 

CXCMD.DISAPPEAR command is a request from Exchange that we 

should close our command window. Exchange will not send this 
command if we have no command window. 

CXCMD.ENABLE and CXCMD_DISABLE are sent by 
Exchange to temporarily enable and disable our commodity. 
CXCMD_KILL permanently stops our commodity from running. 

CXCMD_UNIQUE is sent by Exchange when an attempt is 
made at running another commodity with the same name. We inform 
Exchange, through flags in the NewBroker structure, that 1) no 
commodity with the same name should be allowed to run, and 2) that 
Exchange should inform us if someone tries to start one. This allows us 
to pop open our command window if the need arises. 

The Command Window 

I used the new CadTools library to construct my command 
window. It is a very simple window, with only three gadgets; you 
should have no trouble figuring out the code. There is a cycle gadget to 
control which qualifier is going to be substituted instead of the middle 
mouse button. Clicking on this with the left button will cycle through 
all the choices. Holding the shift key down while clicking will cycle in 
the opposite direction. I also included standard button gadgets, labeled 
"Hide" and "Quit". The "Hide" gadget closes the command window 
without stopping the commodity. It is the equivalent of using the 
Exchange program's CXCMD. DISAPPEAR command. The "Quit" 
gadget causes the commodity to stop running. It is the equivalent of 
Exchange's CXCMD.KILL command. 

I did not include a "close window" gadget in the window, 
because I find their use confusing when used with commodities: does 
it just close the window or docs it kill the commodity? To resolve the 
dilemma. I chose to sidestep it. 

The window and gadgets are font-sensitive. They utilize the 
user's default screen fonts. They take this into account each time the 
command window is opened, in case the user changed his font 
scheme. It would have been more memory efficient to allocate the fonts 



once at startup and free them once at the end of the program, but that 
would violate the new flexibility that Workbench 2.0 offers in terms of 
fonts. 

Using MMB_CX 

After compiling the program using the supplied makefile 
make an icon for it by entering the following from a shell (assuming 
that the executable code is in RAM:): 

copy SYS:Tools/Commodities/Blanker . info 
ram :mmb_cx. into 

Click once on the MMB_CX icon and choose the Icons- > Information 
option from the Workbench menu. Commodities use the ToolType 
environment to set program options conveniently, so you can adjust 
these to your liking. ToolTypes follow the general format 
"oplion»value". To specify some option, simply add it to the ToolType 
list. Options usually have some default value, so if you are happy with 
the default value, you do not have to include the option in the 
ToolType list, and your ToolType list can be completely empty. 
MMBJZX understands the following ToolTypes: 

CX_PRIORITY=<priority> 
CX_POPUP=<yes or no> 
CX_POPKEY-<hotkey description> 
MMB_QUAL=<substitution qualifier Co use on 
start up > 

CX_ PRIORITY is the priority at which that the Commodities system is 
to install MMB_CX. This number can range from -128 to +127. The 
higher the number, the higher the priority, and the sooner this 
MMB_CX will see input events. The default is 0, which is fine for most 

purposes. 

Including a ToolType value of "CX_POPUP=yes" will 
instruct MMB_CX to open up its command window when it starts up. 
The default is "no", 

CX_POPKEY is the option for specifying the hotkey 
description by which we bring up MMB_CX's command window. The 
default is "midbutton help". 

The first three options listed are standard commodity 
options, and all commodities should support them. The last option, 
MMB_QUAL, Is MMB_CX-specific. It tells the program what qualifier 
you want as your default qualifier, so that you do not have to open the 
command window and set it every time you start the program. The 
default is "Ishift". If you want something different, say for ProWrite. 
add "MMB_QUAUIair to your ToolType list. MMB.QUAL under- 
stands "Ishift", "rshift", "lalt", "rait". "Icommand". "rcommand". and 
"control". 

Conclusion 

The Commodities system allows one to easily modify the 
way that input events are interpreted on the Amiga. They are easilv 
programmed, and do not take much memory at all. They are also 
easily learned; I am definitely no expert on them, or on programming 
the Amiga in general, but I managed to create something useful in a 
relatively short time. I also did not have to delve into the strange world 
of interrupts to accomplish this; 1 let the Amiga do it for me. Com- 
modities have a wide variety of uses, such as screen blankets, mouse 
accelerators and mouse blankers, and programs like MMB_CX. Their 
object-oriented nature meshes nicely with the new object-oriented 
nature of Workbench 2.0, and ensures their expandability. In short, I 
found it extremely profitable to work in Commodities* 
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MHB_CX . c 



•• A Commodity to control a middle mouse button. 
■ • 

•• Scott Palmateer. 17 July 1992 



•include otring.h* 
•include <exoc/types.h> 
■include <exec/ports.h> 
■include <devices/inputevent .h> 

■ include < intuit ion' intuit lor. . h> 
■include <libraries/commodit ies.h> 
■include <workbench/workbench.h> 
■include <workbench/startup.h> 
■include <libraries/gadtools.h> 

■ include < intuit ion/gadget cl ass. h> 

•include <proto/exec.h> 
■include <proto/intuition.h> 
•include <proto/graphics.h> 
•include <proto/commodities.h> 
•include <proto/wb.h> 
•include <proto/icon.h> 
•include <proto/gadtools.h> 

•define REQ_REL 37 /• required release oflibraries 



•define KMB_NAME 

•define MMB_DESCR 

events' 

•define kmbtitle 



■MMB_CX- 

"Transforms 



middle mousebutton 



'HMB_CX vl.O" 



:ne DEFAULT_PRI 

•define DEFAULT_POPK£Y 

•define DEFAULT_POPUP 

•define DEFAULT_QUAL 

•define HMB_HOTKEY 

•define OFFSET 

•define HIDE_GAD 

•define QUIT_GAD 

■define CYCLE_GAD 

•define KMB_IDCMP 

•define H1DETEXT 

•define QUITTEXT 

•define CYCLETEXT 



•midbutto:. 

"no" 

-lohiff 

1 

6 
D 
1 
2 
(CYCLEIDCMP I BUTTONIDCMP 

r DCM P_R E FR ESHW I NDOW ) 
•H;de" 
"Quit" 
'Transform HMB into:" 



/" FUNCTIONS DEFINED 

void saveds 

void 

void 

void 
void 



IN THIS PROGRAM; ■ 
requalifylregister CxMsg -cxm) 
openupUnt argc. char "argv[)l 
closedown (int errnumi ; 
reqprint (char *txt ) ; 
do_comwindow(BOOL appear); 



/■ Disable SAS/C CTRL-C handling */ 
void chkabort (void) {) 



/• REQUIRED DATA FOR cback.o: •' 
long _stack 2048. 

^rio: ; 0. 



_BackGroundIO 
char "_j>rocname 



0; 

WD HMO ; 



/• GLOBAL VARIABLES: »/ 

char "v « "\OSVER: HMB_CX vl.O"; 



struct 


IntuitionBase 


"IntuitionBase ■ 


NULL; 


struct 


GfxBase 


-GfxBase 


ndi : 1 


struct 


Library 


• ■"■.; | 


= NULL; 


struct 


Library 


"iconBase 


» NULL; 


struct 


Library 


•GadToolsBase 


^ NULL; 


struct 


MsgPoi c 


"HHB_P0rt 


= NULL; 


struct 


Window 


*HNB_Window 


* NULL; 


struct 


Gadget 


•MMB.GLlst 


= NULL; 


CxObj 




*HMB_Broker 


* NULL; 


int 




Qual index 


■ 0; 


BOOL 




Popup 


= FALSE 



INITIALIZATION STATEMENTS: •/ 



struct NewBroker MHB_NB » ( 
NB_VERSION. 
HHB_NAKE. 
KMB_TITLE. 
MHB_DESCR. 

NBU_NOTIFY I NBU_UNIQUE. 
COF_SHOW_HIDE. 
0. 

NULL. 

); 

IX MMB_IX 

IX_VERSION. 

IECLASS_RAWMOUSE. 

0. 

-.. 
'-. 

0. 


li 



/" nb_v«r»ion 
/• nb_Name 

/" nb.Titl* 
I* nb_Descr 
/■ nb_Unique 
/• nb.Flags 
/• nb.Pri 
/" nb_Port 
/• nb_ReservedChann*l 



ix_version 

ix_Class 

ix_Code 

ix_CodeMask 

ix_QuaI .:.■■: 

ix_Qualmask 

ix_QualSaroe 



•define NO_ERROR 100 

:.'TLlB_ERROR 

« GFXLIB_ERROR 1 

•define CXLIB_EBROR 2 

•define ICONLIB.ERROR 3 

•define GTLIB_ERROR 4 

•define PORT_ERROP 5 

•define CX_ERROR 6 

•define screen_errop 1 

ne VI_ERROB B 

•define GAD_ERROR 9 

r.e WIN_ERROR 10 

•define BROKEP_ERROR 11 

•ErrMsgtl * ( 
•Error opening Intuition Library!". 
"Error opening Graphics Library: ". 
"Error opening Commodities Library! 
"Error opening Icon Library!". 
"Error opening GadTools Library!". 
"Error opening port!'. 
■Error opening Commodities Objects! 
"Error opening public screen!". 
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"Error getting screen's visual info: 

•Error creating gadgets!". 

"Error opening window!". 

•Cannot start another HMB_CX!" 

); 



char 'OualLabelsIl = 1 

"Left Shift". 

"Left Alt", 

"Left Amiga", 

■Control". 

>; 
char 'QualNamesU = ( 

"lshift". 

■lolf , 

"1 command". 

"control". 

t: 
UWORD QualvaluesM = ( 

I£QUALIFIER_LSHIFT. 

IEQUALIFIER_LALT. 

IEQUALIFIER_LCOHMAND. 

IEQUALIFIER_CONTROL 

): 
USHORT OualCodesI) > ( 

0x60. 

0x64. 

0x66. 

0x63 

): 



"Right Shift". 
"Bight Alt". 
"Right Amiga". 
NULL 



•rshiff. 
"rait". 
"1 command' 
NULL 



IEQUALIFIER.RSHIFT. 

IEQUALIFIER_RALT. 

IEQUALIFIER_RCOMMAND y 



0x61. 
0x65. 
0x67. 



/• ./ 

void nainlint argc. char "argvM) 
( struct Message "msg; 

struct intuiKessage *imsg: 
struct Gadget "gad; 

ULONG msgid; 

ULONG msgtype; 

BOOL quit = FALSE; 

openupfargc. argv) ; 
if (PopUp) do_comwindow(TRUE) : 
while ( !quit) { 
if (MHB.Window) 

Wait ( (l<<MMB_Port->mp_SigBit) I 

(l«KHB_WindOw.»u M rPort->*p_SiBlUtH 
•1m 

M«ltClc«Ma.tort-Mp_SlsSlcii 
-nile (msg ■ (struct Message "lCetMsg<MMB_Port> ) [ 
msgid = CxMsglDl (CxHsg Mmsg); 
msgtype - CxMsgTypel (CxMsg *)msg); 
ReplyKsg(mag) ; 
switch (msgtype) ( 
case CXM_I EVENT: 

if (msgid«»MMB_HOTKEyi do_comwi ndow (TRUE! 

break; 
case CXH_COKMAND: 
switch (msgid) { 

case CXCMD.UNIQUE: 
case CXCMD_APPEAR: 

do_comwindow (TRUE) ; 
break; 
case CXCMD_DISAPPEAR: 
do_comwindow (FALSE) .- 
break; 
case CXCMD_KILL: 
quit « TRUE; 
break; 



case CXCMD_DISABLE: 

ActivateCxObj (KMB_Broker. FALSE) ; 

break; 
case CXCMD_ENABLE I 

ActivateCxObj (MHB_Broker, TRUE); 

break; 
) 



br«*k; 



) 



I 



( 



if (l!quit) it IKMB.Window) ) 
while <(MMB_Window) && 

(imsg ■ CT_GetIHsglMMB_Window~>userPort) ) ) 



msgtype a imsg->Class; 

gad ■ (struct Gadget •) imsg- >I Address ; 

GT_ReplyIMsg(imsg) ; 

switch (msgtype) ( 

case IDCHP_GADGETUP: 

switch (gad->GadgetID) ( 
case HIDE_GADi 

do_comw i ndow ( FALSE ) ; 
break; 
case OUIT_GAD: 
quit * TRUE; 
break; 
case CYCLE_GAD; 

Quollndex ■ imsg->Code; 
break ; 
) 
break; 
Case IDCMP_REFRESHWlNDOW: 

GT_BeginRef resh (MMB_Window) ; 
GT_EndRef resh lMMB_Window. TRUE) ; 
break; 



ActivateCxObj (MHB_Broker. FALSE); 
closedown (NO_ERROR) i 



/• Here is the function that opens up all the libraries. 

ports, objects, etc. 
V 

void openuptint argc. char *argv{)> 
( CxObj -filter; 

CxObj "customobj ; 
char "x, ••MHB_TT; 
int n; 
BOOL found; 
/• open our libraries: V 
IntuitionBase = (struct IntuitionBase •» 

OpenLibrary ("intuition. library". REQ_REL) ; 
if (! IntuitionBase) closedown! INTLIB_ERROR) ; 
Gf xBase ■ (struct Gf xBase *) 

OpenLibrary ("graphics. library' , REQ_REL> ; 
if ( !Gf xBase) closedown <GFXL1B_ERR0R) ; 

CxBase * OpenLibrary ( "commodities. library". REQ_REL) ; 
if UCxBase) closedown(CXLIB_ERROR) ; 

GadToolsBase = OpenLibrary Cgadtools. library". REQ_REL); 
if (SGadToolsBase) closedown(GTLIB_ERFOR) i 
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/* Get user's cooltype prefs from Workbench or CLI : * 

IconBase * OpenLibrary Cicon. library'. REQ_REL) ; 

if ( ! IconBase) closedown (ICONLIB_ERR0R) ; 

HMB_TT ■ [char 'MArgArraylnit large, argv) ; 

MMB_NB.nb_Pri = Arglnt (MMB_TT. •CX_PRIORITY' . 

DEFAULT.PRI); 

x ■ ArgString(KMB_TT, "CX_POPUP- , DEPAULT_POPUP) ; 

if (striemptx. -yes")*-0l PopUp » TRUE; 

K * ArgString(HMB_TT. •HMB_OUAL", DEFAULT_QUAL ) r 

n=0; found-FALSEj 

while (Ufound) && (QualNames[n) ) ) { 

if (stricmplx, QualNames|n) > »»0) ( 
Quallndex ■ n; found = TRUE; 
) 

else n++j 

) 
X • ArgString(HMB_TT. •CX_POPKEV. DEFAULT_POPKEY) ; 
ArgArrayDonet ) ; 

f* we're done with icon. library now V 
CloseLibrary (IconBase) ; 

t* gee our pore for communicating with Commodities: •/ 
MMB_Port • CreateMsgPort ( > ; 

if <!MMB_Port) ClOBedown(PORT_ERR0R) ; 

/* now create the commodity objects • 
/" first the broker: •/ 
MMB_NB.nb_Port = HMB_Port; 
MMB_Broker = CxBroker <6.MMB_NB. NULL); 
if |!MMB_Broker) closedown(BROKER_ERROR> ; 
I* this next function creates a filter/sender/translator 

filter = HotKey(x. MMB_Port. HMB_HOTKEY); 

if (ifilter) closedowniC_ERROR) ; 

AttachCxObj (KMB_Broker, filter): 

if (CxObjError (filter) » SetFilter (filter, 

DEFAULT_POPKEYl ; 

/• now we create the actual KMB filte: » 

filter = CxFilter(NULL); 

if tlfilter) closedown(CX_ERROR> ; 

SetFilterlXlfilter, &MMB_IX) ; 

AttachCxObj (MMB_Broker. f liter I ; 

/* and here we link in our custom function */ 

customobj * CxCustomtrequalify. Ol; 

if ( 1 customobj) closedown(CX_ERROP) ; 

AttachCxObj (filter, customobj ) ; 

/• everything is ready; activate our Commodity! •/ 

ActivateCxObj (HMB_Broker. TRUE); 

) 

/• V 



/■ This function closes down everything that we opened. 

•/ 

void closedown (int errnum) 

( struct Message "mag; 

do_comwindow (FALSE) ; 

if (HMB_Broker> DeleteCxObjAH (KMB_Broker ) ; 

if (MMB.Port) ( 

while (msg = GetMsg(HHB_Port) I ReplyHsg(msg) ; 

DeleteMsgPort (KMB_Port> ; 



if (GadToolsBase) 

if (CxBase) 

if iCf xBase) 

if (IntuitionBase) 



CloseLibrary(GadToolsBase) .- 
CloseLibrary (CxBasel ; 
CloseLibrary ( 

(struct Library 'ICfxBase); 
CloseLibrary! 



(struct Library *► IntuitionBase) ; 
if (errnum != NO_ERROR) reqprint (ErrHsglerrr. . 
exit 10); 



/ 



/• Here is the funcion that transforms a middle 
mousebutton 

event into a left-shift event (or whatever else we 
have 

chosen). Note that this function should be very 
Bimple 

and quick, since it will run as part of input. device: 
*/ 

void saveds requalify (register CxMsg "cxro) 

I register struct InputEvent 'ie; 
if lie » (struct InputEvent ')CxMsgData(cxm) ( 
if (ie->io_Code == IECODE_KBUTTON) < 
le->ie_Code = QualCodes iQuallndex] ; 
ie->ie_Oualifier 6* -iequal:fier_midbutton; 
io->ie_Qualifier 1= QualValuesIQuallndexl ; 
ie->ie_Class = IECLASS.RAWKEY; 
) 

else if (ie->ie_Code == (IECODE_MBl)TTON \ 
IECODE_UP_PREFIX) ) ( 

ie->ie_Code » IQualCodesIQuallndex] i 
IECODE_UP_PREFIX); 

ie->i«_Class * IECLASS_RAWKEY; 

) 

else if (ie-»ie_Qualifier & IEQUALIf:er_midbutton> 
( 

ie->ie_Oualif ier &■ -IEQUALIFIER_MIDBUTTON; 

ie->ie_Oualifier I" OualValues[Ouallndexl r 

) 



/. . 

/* Just a little utility program to throw some 
information 

onto the screen... 
'/ 

void reqprlnt (char *txt) 
( struct EasyStruct e; 

e.es_StructSize = sizeof (struct EasyStruct); 
e.es.Flags = NULL; 
e.es_Title « HMB_NAME: 
e.es_Text Format = txt; 
e.es_GadgetFormat ■ "OK"; 
EasyRequest (NULL, &e, NULL, NULL); 
I 
/• ./ 



.s is the function that handles opening the command 
window, through which we can control the behavior of 
the commodity. If told to open the window, it makes 
sure that the window is not already open; if told to 
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ng.ni 


ont; 




-SET; 


ng • ng_TopEdgo 


'WBorTop* (gheight*4J , 


ng.ng_Widih 


Text Length <fc ( screen- >Rast Port 1 . 




HIDETEXT, 




strleniHiDE. 



ng.ng_Wtdth :,- >RastPort) , 

CYC ' 

ETEXTH 

• OFFSET; 

■ 
r.g.r.q 

■ 
reateGadget (CYCU 

GTCY.Labels. Qua 
GTCY_Active, Qua i Index. 
TAI 
g) Closedown (GAD_EPHOB) ; 



■ ■ 
WA_Gadgets. 
WA_AutoAdjust. 
:^nerWidch, 
WA_Inner Height 
WA_DragB | 
WA_DepthG 
WA_A-- 

. ■ 



f < 



iwTagstNULL. 
MMB_HAHE . 

■ 
TRUE. 

ng.ng_Wldth.(2"OFFSETI . 
7 "OFFSET r. 



■ 






INULL, screen) r 



1 

:ow) < 

;g; 
Hsg <MMB_Window- >UserPort ; 
GT_ReplyIMsg (imsg I ; 
CloseKmdow fHHB_Windowl ; 
Fr w Cedqet o ( MMB.GL I 

. LI.; 
HHB_Window = NULL; 
I 



• OFFSET; 
ng - ng_Height ^height ; 

ng.ng.GadgetText = HIDETEXT; 
ng.ng.GadgetiD = hide_gad; 
ng.ng_Plags 

3) closed 
ng.ng 

ng.ng_Wi>: 



D] 



&ng. TAG_ENDI ; 

■:dth; 

■ Port 



[TEXT I I 



■■SET: 
ng.ng_GadgetText EXTi 

ng.ng_GadgetID - Ot 

ND. g. *ng. TAG_B 
_BU*OR ) ; 

- :■-;)•( 2 "ghe.gl 
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P.O. Box 2140 

Fall River, MA 02722-2140 
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Amazing Computing provides its readers with: 
In-depth reviews and tutorials 
Informative columns 

Latest announcements as soon as they are released 
Worldwide Amiga Trade Show coverage 
Programming Tips and tutorials 
Hardware Projects 
The latest non-commercial software 





AC's TECH Gives You Great Reasons 
to Get Into Your Amiga 

AC'S TECH offers these great benefits: 

The only disk-based Amiga technical magazine 

Hardware projects 

Software tutorials 

Interesting and insightful techniques and programs 

Complete listings on disk 

Amiga beginner and developer topics 



Order a SuperSub and get this great Amiga peripheral 

—World's best authority on Amiga products and services 

—Amiga Dealers swear by this volume as their bible for Amiga intormation 

—Complete listings of every software product, hardware product, service. 

vendor, and even user groups 
—Directory of freely Redistributable Software from the Fred fish Collection 

12 Issues of Amazing + 2 AC's GUIDEs! 

WINTER 1993 AC's GUIDE IS NOW 
AVAILABLE! 




Using the auclio.clov ice 



by Douglas Thain 

Digitized and synthesized sounds can help to make games more enjoyable and utilities feel 
more professional. A simple beep emanating from a program just "feels" better than the Amiga's 
stark display flashing once. However, the audio examples provided in the ROM Kernel Manuals 
are less than clear cut Even with these tools, audio support is not much use without the IFF stan- 
dard sound format at your disposal. This article will help you to include synthesized and digi- 
tized sounds into your programs. 



Audio Baaicfl 



BwCtfOnk KMinds Oil be divided into two main categories: 

digitized sounds and synthesized sounds. The Amiga's hardware 
treats the two in the same manner, but different programming 
approaihe- are needed for each lype. 

Both synthesized and die.iliz.-d sounds are stored in chip 
memory — memory that Ihe Amiga's custom chips have access u > -as .1 
series of integer values ranging from -128 to 127. Each discrete value is 
Known U a sample. The entire piece of memory is .ils<i sometimes 
known as | -ample, but we will reler to it .is a waveform Whena 
waveform is played, the Amiga rapidly passes ■■> C9 the W» ■form and 
clicks'* (he speaker In or out for each value These clicks are turned 



into compressed air waves by the speaker, resulting in sound. 

A synthesized sound is usually a small waveform that is 
repeated many times a second. Such sounds are often simple geometric 
patterns or mixtures of several such patterns. Figures 1 and 2 an* 
examples of synthesized waveforms. Synthesized sounds rarely sound 
like real sounds or instruments, but they take up very little memory 
and are easily created and manipulated in a program. 

A digitized sound is a large sample — anywhere from a few- 
kilobytes to several hundred— that is usually played once slowly. Such 
a sample is recorded using a digitizer. A digitizer measures the same 
sort of compression levels that a speaker emits, then feeds them to the 
computer. The recorded sample is then saved to disk for later use. 
Digitized sounds take some work to load and manipulate, but they 
allow for accurate reproduction of real sounds 



Figure One: Sawtooth Waveform 




I lie I Yi.v,r;tiii 



listing 1. play.c. is a program that demonstrates the 
playback of both digitized and synthesized sounds It is run 
from Ihe shell and takes one argument: the name of a sample 
or )ust "beep." If a name is provided, the program will 
attempt to load an IFF 8SVX file of that name and play it 
"beep" will output a crude sawtooth waveform suitable tor a 
terminal bell 

play.c can be compiled under any standard Amiga C 
compiler except DICE. DICE (as of version 2.05.15) does not 
support the function BeginlOO, which is essential to the 
program. 

play.c should be compiled using long integers Using Manx, 
this is. 



cc -L play.c 

In play.o -lcl32 

play.c has three major components: playsamplef). which sets 
up the device and plays a loaded waveform. loickawwaveO, 
which sets up a simple sawtooth waveform; and 
Ioadsample(), which loads sampled data from an IFF file 
Lei's take a close look at the important parts of these 
functions. 
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to Play IFF Sounds 



Srttiiiu I i) lh<- audio. device 



Before we play a waveform, ho must do four things: secure 
s message port, allocate .1 request block, open the audio.device, and 
allocate an audio channel. 

A new message port is necessary to communicate with the 
device. A nameless message port is created in the usual way; 

struct HsgPort "port; 

>rt<NUlX.O) ; 
iULL) putaCCouldn't open port :-l ; 

A request block is the vehicle that carries data between the 
device and our program The request block we must use lor the 
audio.de* ice is an extended type known as struct lOAudio. This 
structure can be tound in the include file devices/audio.h. This code 
will allocate an 10 Audio: 

lOAudio -request; 

leateExtlOfport.sizeoflstruct IOAudiol); 

iUMtaaNUU*) puts ("Couldn't create request!") , 

Now v. e can open the device, specifiying our request block 
and the name nl the device: 



int error; 

error * QpcnDevicel "audio. device". 0. request, 0» ; 
: or !=0) puts ("Error opening audio. device! " ) ; 

Before we can play a sound, we must allocate a channel The 
channei allocation feature bl pHM Idtd so that several programs can 
compete lor BOUnd generation without blocking out important 
information lor the user, To allocate a channel, a program must 
provide the channels desired along with a priority. These suggested 
sound priorities are taken from the ROM Kerne) Manual: Libraries and 

:Stoppable 
Emergencies 
80 - 90 -Annunciators (Bells and attention sig- 



nals) 



75 - Speech 

SO - 70 - Sonic Cues 

-50 - SO- Ktl 

-70 - - Sound effects 



-100 - -80 



- Background 



For example, a music program might allocate channels for its 
sounds ,11 .1 priority of 25, An annunciator such as our program can 
allocate a channel at 85. This allocation would block out a particular 
channel |usl long enough to allow the annunciator to sound. The music 
program could then continue on with only a momentary loss of sound- 



It is possible (o use the device lommands 
AlXMl) ALLOCATE and ADCMD^FREE to allocate and tree mam 
channels many times, but tor .1 one-shot sound as we will require, it is 
often easier to use the automatic allocation and free features U we set 
up a recjuesl block with allocation information before the device is 
opened, a channel is allocated right away, and our request block is 
ready logo It we QoseDeviccfl without sending an AIX MD.FREE, 
the channel will be deallocated for us. Here's an example oi automatic 
allocation 

•:• L.EFT0 1 
,e RIGHTO 2 



I LEFTO I RIGHTO. 
LBf 

richi 

141 ' 

■ 

tcc{ueot->ioa_Length 

■>P) ; 
request ->ioa_Rt-- 

; ■ 



85; 






>F_N0WAIT; 



error : OpenDev: 

if (error! putsCCou.a 



■..::. 
. ho. device") ; 



Our list o( sets ol channels (in order of preference) is in 
allocmap: first left and right channels 0, then each separately If none of 
these are availible. OpenDev ice() will tail 10. Command must be set !,■ 
ADCMD_ALLOCATE, ioa_Data must point to the allocation array, 
and ioa_ length must he the si/eol the allocation amy. The flag 
ADIOF_NOWAIT makes the action occur right away or fail. Other- 
wise, the command would wait until a channel was free. Finally, the 
priority of the message block must be set to our sound priority: 85 for 
annunciators 



I lax in- a Sam J ilc 



Once the device is opened, playing a sample is relatively 



eas\ 






unHertzl of thecuBtomc: 
' 3579545 



torn ,-12 7 . - 

64.0.' ,64,0.-64, 27 I: 

waver- torml ; 

■ ■ 
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cycles = SO; 



request->ioa_Request . io_Coranand - CMD_WRITE; 
rotni80t->ioa_Fecruest . io_Flags * ADIOF_PERVOL; 
request->ioa_Data > waveform; 

request ->ioa_Length * wavesize; 
raquest->ioa_Period -COLORCLOCK/sanplesperaec; 
roquest->ioa_Volume ■ 64; 
request->ioa_Cycles * cycles; 

BeginIO(recjuesc I ; 
< request ) ; 

CMD_WRlTEsays we arc writing to the device. 
AD10F_PERVOL tells the device to use the period and the volume 
getting! in this request. Without ADIOF_PERVOL. the device would 
use the last values sent 



Figure 2: A "Squared-Trianglc" Waveform 




Waveform is a pointer to the data to be played, and 
wavesize is the length of the data. The waveform used is a mixture of a 
square wave and a triangle wave. (See Figure 2) 

ioa_Period is the number of custom chip clock ticks between 
each sampled value. This value is rarely stored along with a waveform 
because i! in so machine dependent. What is stored, however, is the 
number of sampled values per second that should be played. If we 



divide the number of custom chip ticks/sec (COLORCLOCK) by 
samples/sec, we get the number of tfa ks tor each sample. (See Figure 

Volume ranges from to 64 - the loudest possible suits us 
just fine. 

ioa_Cyclcs is the number of times lo loop through the 
waveform for a sampled sound, once plays the entire sound. A 
Synthesized sound must play many cycles lobe heard. Given the time 
in seconds to ■ play a synthesized simple, the number of cycles 
required is given by timc'samplespersec/ length (See Figure 3) 

The request is sent off to the device by using begin IO<). and 
the waveform begins playing Our program then waits for the sound lo 
finish and the request to return by calling WaillOf). Notice thai 
SendlOO and DolO() are generally not used with audio device because 
they clear device Specific flags such as ADIOF_PERVOL and 
ADIOF_NOWAIT. We must resort to the low level IV n order 

to preserve these flags. 



I sinjr Synthesized Sounds 



The function loadsav. wave!) sets up a synthesized sound for 
playsampleO to use The waveform we will vim- is stored in sawwave. 
Notice that loadsawwavcf) allocates ■ new block of chip memory to 
copy sawwave into We can't tell whether sawwave is in chip memory 
or not without allocating the memorv ourselves '/ 1- essential that all 
waveforms be stored in chip memory. 

When creating your own synthesized sounds, there are two 
basic guidelines to follow: 

- Make waveforms connect smoothly. The beginning and 
end of your waveforms should have similar values and slopes 
Without this continuity, a waveiorm will click or pop each time it 
repeats. 

• Make waveforms as much positive as negative A 
waveform's volume is determined by the average absolute distance 
from the zero level A waveform which is shvavs on one side ol the 
zero level will have little or no volume 



COLORCLOCK 



samplespersec 



COLORCLOCK-3579545 

ticks x sec _ licks 



sample x sec 



Cycles x length cycles x samples x sec 

samplespersec cycle x samples Time kecondfcO 



Time x samplespersec — Cycles 

length 



Loading IFF 8SVX Sounds 



The Interchange File Format was developed by Electronic 
Arts and adopted by Commodore-Amiga as a general data standard. A 
complete discussion ol the standard is far beyond the scope of this 
article and can be found in the ROM Kernel Manual I ibranes M^i 
Devices. However, a quick review ol the 8SVX format is simple 
enough to develop a loader for our program 

Commodore has provided such tools as the iflparse. library 
to make manipulating IFF files easier Hut tor reading simple fUefl H 
We will, it is easier to write our own routines and a\ oid making our 
program dependent on such libraries 

The simplest IFF file is known 
as a FORM A FORM can contain 
manv different sub parts, each 
known as chunks. Each chunk has 
a four letter identifier followed by 
a longword which shows the 
length of the chunk A FORM is in 
fat t Itself I chunk, and can be 
made part ol a larger IFF file. An 
example oi this is an II MM picture 
file .is part ol a larger AN1M 
animation file 

IFF identifiers are represented 
to humans as tour letters, but the 
Amiga prefers to store the 
characters as longwords. For this 
purpose, we create the macro 
MaketDO: 



samplt 
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( ( Ion. j 



. c,d> 



. 



long num.* 



HakelOCF*. '0'. 'R\ 

All this macro does is inkr fbui characters and packs them 
into one variable When the program WMb in a chunk ID, it reads in .1 
longword and compares it to the longword created by MakeiDQ 

RgunH ihowi the layout oi a i>jmc FORm'ssvX An BS\ X 
can contain many chunks pertaining to ih«' bask data 1 he author. 
creation notes. information h» playing the waveform backasamusic.il 
instrument, and mom can .ill be inside the file without gelling in the 
way of the main data 

The two, hunks we will be Interested mare the VHDK and 
BODY chunks. The VHDR chunk only contains one field we need: the 

sample* [htmvoiuI tield (See Figure 4.) [he BODY field contains only 

the raw sampled data Our program must be flexible enough to skip 
over everything else that the Me may contain 

Looking at figure 4. here are the ttCpa we nui-t take to read 
in the waveform 



1. Make sure the first longword is KIKM 

2. Skip the next longword (the FORM length) 

3. Make sure the next longword is 8SVX 

4. Search for VHDR 

5. Skip the next 4 longword s 

6. Read in the next word as samples per second 

7. Skip the next word 
8 Search for BODY 

9. Read in the waveform length 

10. Read in the taw data 

The function loadsamplef) performs .ill ol this and b 
commented to show each step of the waj 



And that's it' playsampleO is perfect to be placed entirely 
inside another program— all the device work lakes place completely 
inside of it. With the removal of global variables, loadsampleO can be 
used js a genen) loader lor all the sounds a program might need. As 
the program stands, it s perfect f.ir playing sounds from an AmigalX *• 
icrifX 
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Listing 1 



iy.c 

by Douglas Thain 

Loads and plays an IFF BSVX sample or does a 

simple beep. 

Compile using long ints - using Manx: 

cc -L play .c 

In play.o -lcl32 

Standard Amiga code but can't compile under DICE - DICE 
doesn't have BeginlOO in c. lib or amigas.lib. . . 



Ida < libraries 'dos.h> 
■ include <devices/audio.h> 

• include <exec7metnory . h> 

I' macros for IFF •/ 

"define Ka<e:Dla,b,c.d) I (long) Ia«24) Ub«16) I (c«8) I Id) ) 

•define ID_FORMKakeID( 'F' , '0'. "R*. 'M*J 

•define ID_8SVXMakeID( '6\ 'S' , 'V . 'X'l 

•define ID_VHDRMak*ID(*V* . *H' , 'D'. 'R') 

•define ID_BODYXakeID( 'B' , '0' . 'D' . 'V ) 

/* audio channel definitions •/ 
•define LEFTO 1 

• define RIGHTO 2 
•define PIGHT1 i 
•define LEFT1 8 

f* custom chip clock speed •/ 
•define COLORCLOCK 3579545 

" function prototypes "/ 
BPTR "Open ( ) ; 

void -AllocKe: 

void "CreateExtlOO : 

void "SetFunctiont ) ; 

struct MsgPort "CreatePortO ; 
struct Library 'OpenLibrary : 



void 
void 



playsamplel ) . loadsamplei l ; 
loadsawwavel ) .closedown!) ; 



/• channel to use .- in order of preference */ 
UBYTEallocmapIJ - ( RIGHTO. RIGHT1 .LEFTO. LEFT! J; 

/" sawtooth waveform to use if no sample speci f led •/ 
UBYTE sawwave [ ] * < -127.-64.0.64.127 )s 

/■ variables for sample data ■/ 

BPTR •file-KULL; 

UBYTE "waveformaNULL; 

LONG waves ize; 

UWORD samp lesper 3*C ; 

UBYTE cycles; 



main(argc.argv) 
int argc; 
char "argv| 1 ; 
l 

/* If no argument, show command format •/ 
if(argc!-2) ( 
puts ("Usage: play <samplenamelbeep>" ) ; 
exit (20) ; 

) 

• argument was "beep", setup sawwave. 
Otherwise, load sample •/ 
•^rcmpfargvllj.-beep") ) loadsawwavel); 

loadsample(argv|U ) : 

/• Do it! •/ 
playsamplel); 

/• exit V 
closedown(O) ; 

) 

/■ closedown (I cleans up only structures that were used •/ 

voidclosedown(err) 

int err; 



iveforml-NULL; 
I e ! 9NULL) 
if (err==15) 
exit (err) : 



void loadsawwave ( ) 



FreeMemlwaveform.wavesize) ; 
Close(file); 
puts ("Not a valid IFF BSVX file!"); 



/• sawwave must be copied into chip memory •/ 
woveform=AllocMan(sizeof (sawwave) ,MEMF_CHIPIHEHF_PUBLIC) . 
if (waveform»aNULL) closedown(20) ; 

strncpy (waveform. sawwave, sizeof (sawwave) ) ; 
samplespersec ■ 900; 
cycles a 40; 
wavesize > sizeof (sawwave) i 



1 



/ " loadsamplet ) con massage and load a FORM 8SVX but doe! 

not understand conglomerate IFF files */ 
void loadsample(name) 
char *name; 
( 

int size, x.- 
LONG tmp; 

/■ nab the file passed to us •/ 
file » Open (name .MODE_OLDFILE) ; 
if (f ile==NULL) i 

puts( "Couldn't open file!") ; 
closedown(20) ; 
) 

/• First longword must be 'FORK* * 
size - Readlf ile.&tmp, sizeof ILONG) I; 
if (size! -sizeof (LONG) ) closedownl 15) ; 
if (tmp!-ID_FORM) closedownl 15) ; 

/■ next is discarded ■/ 
size > Read ( file. &tmp. sizeof (LONG) t ; 
if (size! ^sizeof (LONG)) closedown ( 15) ; 
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/• next must be -8SVX" •/ 
size * Readif ile.fctmp.sizeof (LONG) ); 
if (size! =sizeof (LONG) ) closedown US) ; 
if (tmp!«ID_8SVX) closedown! IS) ; 

/• now find a -VHDR" • I 
while(l) ( 
size ■ Read If 1 le.it mp. si zeof (LONG) ) ; 
if (size!=sizeof (LONG) J closedown! IS) ; 
if !tmp-"I n _VHDR) break; 



/" first 4 longwords are no use to us */ 
for <x*0;x<=3;xt. I ( 

size = Read(f ile.itmp. si zeof (LONG) >; 
if(siz«!>sizeof (LONG)) closedownUSI ; 

) 

/• the next word is sampling rate */ 
size = Readif ile.&samplespersoc.si zeof (UWOPD) >; 
if (size! »si zeof (UWORD)) closedown ( IS) ; 

/* next word is no use to us V 
size = Read(f ile,4tmp,sizeof (UWORD)) ; 
if (size'-sizeof (UWORD)I closedown(lS) ; 

/* now find a "BODY* •/ 
while(l) ( 
size ■ Readif ile.it mp.si zeof (LONG) ) ; 
if (size! =sizeof (LONG) > closedown! 15) ; 
if (tinpn.iD_BODY) break; 
) 

/* next longword is size of sample */ 
size ■ Readifile.iwavesize.sizeof (LONG)); 
if (size!=sizeof (LONG)) closedown(lS) ; 

/• can we allocate that much memory? •/ 
waveform = 

AllocMem(wavesize,KEMF_CHIPIKEMF_CLEARIHEKF_PUBLIC) 
if (waveform==NULL) closedown! 16) ; 

/• read in as much as we can get •/ 
size ■ Readtf ile. waveform, waves ize) ; 
/• as long as we got SOMETHING, we'll play it •/ 

if(size«0) closedownllS) ; 

/• and close the file •/ 
Close(file) j 
file - NULL; 

cycles = 1; 
return; 



voidplaysampleO 
1 

struct HsgPort "port; 

struct lOAudio •req; 
int erroralj 

/• create a no-name port */ 
port >» CreatePort (NULL.Ol ; 
if (port ! -NULL) ( 

/* allocate a request block */ 



req = CreateExtlOfport . sizeof (struct lOAudio) ) ; 
if (req! -NULL) { 

/* set up the block so that OpenDevicel) will 
automatically allocate a channel from 
allocmapU for us */ 
req->ioa_Request . io_Message.mn_Node.ln_Pri * 8S; 
req->ioa_Request .io_Flags = ADI0F_NOWAIT; 
req->ioa_Request.io_Command « ADCMD_ALLOCATE; 
req->ioa_Data - (UBYTE •) ollocmap; 
req->ioa_Length « sizeof (allocmap) ; 

error * OpenDevice ("audio. device' . 0, req, 0) j 
if (error"0) { 

/* set up the block with our data •/ 
req->ioa_Request . io_Command = CMD_WRITE; 
req->ioa_Request.io_Flags ■ ADIOF_PERVOL; 
req->ioa_Data « waveform; 
req->ioa_Length * wavesize; 
req->ioa_Period = COLORCLOCK/samplespersec; 
req->ioa_Voluroe « 64; 
req->ioa_Cycles ■ cycles; 

/• begin the sound (DoIO!) or SendlOO can't 
be used - they will corrupt 10. Flags) •/ 
BeqinlO(req) ; 

/* wait for it to finish •/ 
WaitlO(req); 

/' close everything up '/ 

cioseD«vice(req) ; 
> 
DeleteExtlOlreq) j 
) 
DeletePort (port) ; 
I 
if (error) puts ("Error opening audio, device' ) ; 
return; 







Please write to: 

Douglas Thai ii 

c/o AC'S TECH 

P.O. Box 2140 

Fall River, MA 02722-2140 
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Make Your Own 3-D Vegetation Objects 



by Laura M. Morrison 



An earlier article described how images can be built up of 
'tiles' using iterated function systems to create self-similar graphics. 
See Reference 1 . It gave a way of placing tiles for 2-D images using 
mouse clicks, and showed how to use Cramer's rule lo get the 
transformation coefficients. Although the same method should work 
for placement of 3-D tiles to get 3-D transformations, mouse clicking 
on a flat screen for 3-D placement can be Imprecise and confusing. This 
article describes a different way of getting transformations for 3-D self- 
similar iterated function system objects. 

The transformations that place tiles and whose iteration 
produce self-similar objects, are known to be composites of translation, 
scaling and rotation. With a knowledge of these simple transforma- 
tions, the computer artist, working from his idea, or sketch, of how he 
wants the completed object to rum out, can easily write specif ica lions 
('specs') describing each tile's placement. 

Illustration I pictures the relationships used to derive 
equations for these transformations For simplicity thev are given for 
the x-y plane only. The equations have the general form: 

P* (x' ,y ,2' 1 s 

f (P(x,y.zt.sx.sy.Sz.h, j,k. (xf.yf ,z£n 
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Most discussions of scaling and rotation assume the origin 
as the fixed point. That form is not useful when applying the transfor- 
mations, as in tiling, to parts of a complex whole. It is desirable to be 
able to specify the fixed point of the transformation. More useful 
equations that include a non-zero fixed point can be derived as 
follows; 

Illustration 1(b) depicts the scaling relationships. Scaling 
changes the distances between points. One point always remains fixed 
and its distance to each other point changes by a scale factor. The x, y, 
and / distances change independently and the scale factors for x, y, 
and / need not be the same. To derive expressions for the coordinates 
of the scaled point P(x',y>'), given a specific fixed point, Pf(xf.yf,zf>, 
we can start with identity: 

K » Xf + (X - Xf> 

y » yf • (y-yf) 
z ■ zf • (z-zfl 



These simple identities expresses any point in space in 
terms of its distance from the fixed point. The trans- 
formed point will want to have the same form but the 
distance from P to Pf scaled up or down. Multiplying 
the distance between points by a scale factor gives: 



where P is the transformed point, Sx,Sy,and Sz are the angles of 
rotation about the x-.y-,z-axis (or lines parallel with these axis); h.|„wd 
k are translations along the x-,y- and z-axis; and Pf(xf ( yf,zf) is the fixed 
point. The transformations used in functions systems arc composites of 
these three simple planar transformations. 

Illustration 1(a) shows the translation relationships. The 
coordinates of the transformed point, P*(x*,y',z'>, are the coordinates of 
the original point, P(x,y,z), but shifted up or down, right or left, 
backwards or forwards, by adding quantities h to x, j to y, and k to / 
The equations are: 



-- ' 



x" : xf • Sx-(x-xf ) 
y = yf . SyMy-yt) 
z' - zf • Sz't- 

(This checks when (xf,yUf) = (0,0,0), or when (xf.yUfl = 
(x,y,z).) Clearing and rearranging terms results in the 
forms: 

x- - Sx*x . xf • 

y*v - '/! < l-Syl 
z' • Sz'z • zf (1-Sz) 

where the second term of each equation is constant, the 
same for all points P(x,y,z). 

Illustration 1(c) depicts rotation relationships We 
can use the formula for the sine and cosine of the sum of 
two angles: 

cosd • phi) .coal "cob (phi) - sini'Bin(phi) 
• phi) = sinl-costphi) ♦ cosl'sin(phi) 

and the identities. 

x = r'cos (phi I 
■sin(phi I 

which, when rearranged, give: 

r'cos(phi) = x - xf 
r'sin(phi) = y - yf . 

Referring to the diagram we find an equation lor the transformed point 

is 
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x" - r'cosil - phi) • xt 
r'stnll . phi) - yf 

Substituting, ihen rearranging gives Ihc final expressions for 
the coordinates of the point in the x-y plane rotated about a line 
parallel with the z axis through the fixed point: 

x' ■ xf «(x-xf )*cos» - ly-yll -sin« 
y' =yf • (y-yf Ccosf • <x-xf>'sin» 

Analogous formula hold for transformed points in the x-z plane and 
the z-y plane. 

Trigonometry and Analytic Geometry arc the highest 
mathematics needed. See any introductory Analytic Geometry text. 
(e.g.. Reference 2) 

Each tile requires 12 numbers (zeros count) to specify the 
composite transformation that maps the 3-D whole into the 3-D tile. 
These specifications, or 'specs', describe directly what the transforma- 
tion must do. The user writes four sets of three numbers to an ASCII 
file to be read by the 3-D_IFS_decoder program. Table 1 lists the 
specifications for placement of tiles of Fern 1, shown in Illustration 
3<a). (b>, and (c). The first six numbers are the x, y, and z scales and 
offsets. The determine size and position of plots on the screen and are 
not part of the transformations. Each tile requires four sets of three 
numbers 



Note that the size of the whole is only implicitly defined by the system 
of transformations. The scale factors give relative sizes. 

The first set of three numbers for each tile In the 'specs' file 
are the amounts to move the the tile to bring it into position for 
rotation into its final position. For example to translate pixels in the x 
direction. -15 pixels in the y direction, and pixels in the z direction 
the "specs' would be: 



Q.O 



-15.0 



0.0 



Since the fixed point has y ■ 350 near the bottom of the screen. Adding 
-15 to y transforms the y value to y - 335, up the screen. The scaled tile 
is to be moved 15 pixels up. 

The third set of three numbers are three angles. They tell 
how much to rotate about the x-axis. y-axis, and z-axis (or, lines 
parallel with the x-, y-, or z-axis) respectively, to place the tile in its 
final position in the whole. For example, to rotate the tile 180 degrees 
about line parallel with the y-axis, degrees about a line parallel to the 
x-axis and 0.9 radian clockwise about the z-axis the 'specs' are: 



0.0 



3.142 -0.9 




• ram 
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The fourth set of three numbers give the coordinates of the 
scaling fixed point. They are the same for each tile of Fcm I. They are: 

160.0 350.0 160.0 

The numbers refer to Amiga screen coordinates. Although these are 
integer pixel amounts they arc written in floating point because the 
program calculates in floating point. (The fixed point of the rotations is 
calculated by 3-D_IFS_decoder program.) 

The second set of three numbers arc the three scaling factors. 
They describe what percent of the whole the size of the tile's x, y, and z 
dimensions should be. For example, a tile to be 3/ 10 the width of the 
whole, 4/10 its height, and 3/10 its depth would have the set of scale 
factor-. 



0.3 



0.4 



0.3 



Positive numbers rotate counterclockwise, negative numbers rotate 
clockwise. The angles of rotation are expressed in radians. They will 
have values between 0.0 and 2*3.1418.. 

In writing specifications for a tile it may be helpful to write a 
general description first. Give a verbal account of 
how the computer is to transform the whole in order 
to get the tile. For example, "... Make a tile a little less 
than half the size of the whole and proportionately 
thinner. Make it branch out from the main stem only 
a little way up the stalk. Also let it tilt backwards 
slightly." Then, translate this description into the 
twelve numbers. Learning the basic information in 
Illustration 1 (a), <b), «nd (c) can also be helpful to 
writing specifications. 

During iteration the decoder program performs 
the component transformations in sequence instead 
of by evaluating one vast complex formula. Such a 
formula could be derived by substituting, combining 
terms and clearing expressions. It would be a single 
transformation with coefficients in three-dimensions 
analogous to the coefficients defined by mouse clicks 
for the two-dimensional iterated function systems. 
The order in which component transformations 
are applied makes a difference. The transformations 
are not commutative. Different orders give different 
results The order chosen here is easy to learn and it 
simplifies, clarifies, and routinizes 'specs' selection. It 
provides a routine procedure for the user to follow 
while learning to imagine the desired image and 
express its tiles in terms of transformations of the whole. This order is 
appropriate to defining tiles for vegetation such as ferns and trees as 
described here. At some point the user may want to experiment with 
the order of transformations if only to check what difference the order 
makes. 

Illustration 2 depicts the sequence of scale, translate, and 
then rotate as the results of the corresponding specifications during the 
placement of tiles of Fcm 1. The scaling fixed point is the lower tip of 
Fern 1 (a). First scale the whole with fixed point the bottom most point 
of the whole, as in (b) Next translate the tile to position for rotation as 
in (c). Last, rotate the tile about a line parallel with the z-axls as in (d). 
The next tile is defined similarly except it was rotated 180 degrees 
about the y-axis to flip it over before slanting it clockwise 0.9 radians 
as in (e). The large top tile was scaled, (0, translated, (g), and rotated 
about a line parallel with the z- axis 0.2 radians and about a line 
parallel with the x-axis -0.25 radians, (h) 
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Illustration 2{a) shows a different fern, hern 2, built up 
completely of miniature models of the whole. Table 2. gives the 
Specifications for Fern 2 as they would be submitted to 3- 
D_IFS_decodcr program. Note that when a segment of the stem bends 
the next segment must be translated to )om it. This is different from 
Fern 1 which seemingly adjusts automatically. Fern I exploits the sub- 
tiles of the large top tile. Besides explicit tiles the transformations 
produces sub-tiles whose placement can be exploited to build up an 
object. Unlike Fem 2, which is composed of many tiles, Fem I was 
built of only three. One tile was specified as a much larger replica o| 
the whole so the transformations produced a fem of seemingly many 
tiles. Note that each segment of the bent stem has been placed correctly 
and automatically by the transformations. Since Fern 2 was built up of 
many same-size tiles each segment of stem had to be specifically 
translated to sit on the segment below. As described so far, Fem 2 is 
two-dimensional. Its orthogonal projections on the x-/ and /-v planes 
are lines. The user can experiment by giving the fem a twist about the 
vertical or bending it backward or forward to see the effect on the 



ILLUSTRATION 2. 




To avoid large files that cannot be opened or even contained 
on one disk, the program writes the object point set to .i sen.- of titer- 

<outpur._imao.e_f ilename>. 
<output_iM<je_filenairie>50t .2 
. . . etc. 

It writes only so many points of the object to a numbered {'oulhleVt 
Hie, closes it and opens a new numbered file CoutfileN*!'). These! of 
points that make up the object are written with the focni.it ol lour li- 
bit, short integers: 

color register x, y. z . 

The user can make these files any convenient size. The 
number of points the object will have is determined by how long the 
user allows iteration to continue. Since the points are randomly 
scattered their number merely determines the density of the object's 

point sel 
The program 
continues until the 
user Mops n by 
clicking in the 
Close Window 
gadget on the sm.ill 
"uiemp" window in 
(he x-y screen. 
Clicking the 
Close Window 
gadget save^ the set 
of object points and 
the three images to 
RAM; Or, the user 
may key 'q' to quit 
saving only the 
object point- 
J-D IFS.dvcoder 
tvrites, as does each 
program of this 
article, a record of its 
activit) to a (He in 
the same directory 
called 'Run_Notes ' 
3-DJFS decoda 
saves relevant run 
data here .is well .is .1 
user supplied 



projections. 

The 3-D_IFS_decoder program (Listing 1 ) uses the specifica- 
tions to produce the points of a 3-D object. To run the program Bui 
prepare the 'specs' file as described above for the fern. It should 
contain the screen scale and offset values and then four sets of three 
numbers for each tile. (Don't forget to add an end-of-filc 999.9's set.) 
Place the "specs" file in the same directory as the program. At the CM 
prompt, type: 

3-D_IFS_decoder <ouiput_image_ filenarno The program 
te.uis the 'specs' file and randomly iterates the transformations 
described by the specs. It draws three screen images, orthographic 
protections, of the object's front on the x-y plane, of the top on the x-z 
plane and of the side on the y-z plane. 

3-D_IFS_decoder writes the screen images to RAM Ales, In 
raw formal. They must be converted to 1LBM format using 
Commodore's public domain program "raw2ilbm\ To convert to ILBM 
format put a copy of *raw2ilbm' in the RAM: directory. CI) to RAM: 
and type at theCLl prompt: raw2ilbm <fllename> dflxfilename pio 
hi 4 For example. This will add 'pic' suffix and put the H.BM file on the 
disk in the external drive, dfl:. 



Table 1 

Specifications for Fern I. 
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comment it the end of the run I In- user might want to add times and 
dales iu Kim Not. - 

Ruri_Notes collects information about activity In the 
directory When it becomes too long ihe user may want to archi\ <• It 
it- great to know information Is available if needed. No more "how 
was that produced?" 
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Sine* I i>t' has come to have a specific structured meaning it 
E better not to tall the object point seta list but rather a "polnt- 
stf". Each point is 'free standing' and does not follow any other point. 
Sets of point? lor different objects can be combined to make a one 
object by simply adding sets of points together 

Illustration 4(a), (b), and (c> shows a 3-D point-set tree; top, 
front. «nd side, made with the 3-D_IFS_dccodcr program. The 'specs' 
file for the tree is given in Table 3. 

RotaView (bsting 2) reads a file of object points produced 
by 3-D_IFS_decoder and displays an orthographic projection on the K- 
y plane. The user can perform sequences of transformations by keying 
instructions By keying "a*. V, or *g' the user instructs RotaView to 
rotate the object about a line parallel to the x-, y- or z-axis and redraw 
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its x-y projection. Keying '-' before the angle letter reverses the 
direction o( rotation If the user keys V the program saves the 
transformed image and the rotated object point set 

RotaVlew also reads a parameter file 'rvparams ' The 
rvparams file contains the coordinates for the fixed point, the angle 
increments and scale and offset values. The scale and offsets only 
apply to the screen coordinates, not the points of the rotated image. 
Table 4(a) lists the 'rvparams' file lor the tree. 




Kotaview tan be used to view any 3-D point-set object, not 
just vegetation. Try, for example, a wire cube point-set included on 
disk It could also be used to easily produce an animation sequence for 
a rotating object 

For the 3-D vegetation objects to be useful they must be 
converted to input for a 3-D program. The next two programs, 
SculptData and SDtoSC3D do that 

Sculpt3D was «h..sen to import the 3-D vegetation objects 
because it is inexpensive, its file format readily available, and because 
there are, reportedly, public domain programs to convert Sculpt3D's 
files to any other 3-D program's format. See Reference 3. Sculpt3D 
works with triangular faces so the object's points must be transformed 
into tiny triangular faces. SculptData program does this 

SculptData (Listing 3) reads an object point-set produced b> 
3-D_IFS_decoder and expands each point into three points. It selects 
three nearby points at random. It writes the three points and Indfctf to 
three files as raw data for vertices, edges, and faces. SculptData writes 
the final count of venues, edges, and (aces to Run_Notes. 

SculptData reads a user prepared parameter file called 
'sdparams. 1 The first parameter is the edgelenglh which determines tin- 
distance between the triangle of points. The second parameter is the 
number of object points to expand. This number determines the 
object's density and should be made as large as available memory 
permits. Table 4(b) lists the 'sdparams' file for the tree. 



Illustration 4(d) shows the front projection ol the same tree 
as m (a), (b), and (c), where each point has become three points. (This 
expanded point-set was collected from SculptData as a by-prodin t ts it 
worked on its three files. To collect this data add another output Rfc 
and three 'fprinlf statements to the code.) The 'edgelenglh' for the tree 
in Illustration 4(d) was two. The edgelenglh for the tree to be imported 
to Sculpt3D was four. 



TABLE 5 

Ruu_Notes - Record of program activity 

during production of tree '.scene' input file for 

Sculpt3D. 
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SDtoSC3D (Listing 4) reads the three raw data files produced 
by SculptData and converts them to one file in Sculpl3D's '.scene' 
format. SDtoSCID also reads a user prepared parameter file 'ilparams 
Table 4(c) lists the parameter file used to prepare the 'scene' file for the 
tree. The first three numbers are the numbers of vertices, edges and 
faces on the input files. (Available on Run \ote-. ) I he next number 
multiplies point coordinates A factor of 100 was found to be necessarv 
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lo get Sculpt3D to accept the '.scene' file. In the parameter file the user 
also specifics (he colors to be used corresponding to the register 
numbers of the raw data 

Illustration 5 shows the tree .is rendered by Sculpt3D (01 tfl 
converted by Transfer from Sculpt 3 [)s HAM image to lores. The 
HAM image is on disk.) The STACK was set at 200000 and Sculpt !l ) 
was loaded from CI I The image took about 26 hours (0 render on an 
Amiga A 1000 with 2.5 M RAM. 

Table 5 lists the Run, Note* record of the tree's production 



Listing 1 



/• LISTING 1. l-D_IFS_d«codor 
Copyright 1992 by Laura M. Morriaon ■/ 

• include 'otdio.h* 

■ includi • ranaB'd sexttmo.h- 

lon.h" 

■ .onMfle.h* 

• 

32L 
24L 
• DEPTH 4L 



USI 



OxtfO.Oxi 
0x900.0x1 



Sot up tor 



■ •• Lc ;■ 



«990, 

«99. 0x444 )j 



ob)Kl 

»-y plan* . • 



:ace. 

CUSTOK:- rOMBITHAP. 

MULL (; 
3cr««n "BCixy ; 
struct HcwScreen newacriy • l 
0.0,640,400.4.0. 1. 

LACE. 
CU1TOK- NUYMAP, 

:::iLL 1 j 
■ 
■ ■ ■ '■ 
■ 

" 

■ UStMLBdOto 













e 'Open 




• 






' 


■ 




Rl'M/i ■( 








•rpxy; 




- i ' - tl 


• 




Rase Port 


" 




Viewport 


•vpxy; 


struct 


Viewport 


' 








" 






. orM ■ - r.Baia; 


■ 


• 




■ 






stat l< 






" 


-- ■ - 








■: TRANS' 




lalMAXTBANSl 


. 


■ 


y! [MAX 




float 


« 




float 


■ ■ •'. 








■ 


* lost 


■ ■" i . i. 


• 


float 


. • ; ■ i 




■ 


■ 




: char outf ilc[1201: 




atatlcchar b 






Btat lc 








; 










char "argvl i j 







LONG 01 

■true 










FILE 'topen 


* 


. 


'•*i;a; 






: 




■ 


I 




lonBase • i 




r-iry'.Ql j 


• ■ 





n-ij 



Op-- ■■>■". Ot; 

-Lt 

' : iry\n") : 
Clooi 

.0)1 

... 

: 

print: * 

print t ('Copyright 199 2 by Laura H. Morrison*); 

print: ' ..-)• 

lati ac noccssary to 

i screen. ■/ 

. . . 



goto ; 



»panp«. . .n.\n*» 



- .fcxBcaia.ixof fsatij 
.yacale.iyof *s«t); 
facanf Ipp. ' - . izscale.lxot faet I i 

. ie placement!.*' 
tacan: 
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6/ 



(scant (pp,' \t \t '. fcyuli), Izalill; 
(Bcantipp.' %( »1 *, fcxali], fcyettlli 
fsconfipp,' %f %f '. tzali). txflili; 
(ocanftpp.* If %f *. ayflll. fczftil): 
if( xtlil « 99B.0 ) 
< 

!-■: 

if I 1 > (MAXTRANS-l) ) 

( 
print f ('Need more storage. \n" J ; 
goto qultj 

I 
goto readmore; 
1 

ntrane ■ li 
(close (pp) ; 

/• Set up the super bitmap* and open the 
three acreena. */ 

planealte ■ (LCMG) (HIDTH/8) 'HEIGHT; 
bitmxy - (atruct BltKap 'lAllocHem 

laizeof (atruct BltKap) .HEMF_CHIP) t 
If (bltmxy-.HULLI 
< 

printf ('No memory for xy batap atruct. Vn')i 
goto quit; ) 

InttBltHaplbitntxy. DEPTH. WIDTH. HEICKTI ; 
for (i ■ 0[ 1 < DEPTH; i--1 
I 
bl tnoty- >Planea 1 1 ] - ( PLANEPTK) AUocRaater (WIDTH . 

HEIG-HTI ; 
If (bltmxy->Plenea[il -• HULL) 
( 

print f (*xy bitmap planet were nullvn*) ; 
goto quit; ) 

BltCl«ar(bltoxy->Planea It). planealie.il: 
1 

newacrxy.CuatonBitHapa bitmxy; 
acrxy • (atruct Screen •) 

CpenScreenl.navscrxy) j 
if <scrxy.«NULL) 
I 

print f ('Unable to open acreen xy.\n') ; 
goto quit; 

1 
rpxy ■ fcacrxy->RaatPort : 
vpxy ■ fcBcrxy->ViewPort; 
LoadftGB* (vpxy.aMp. 16) j 
nw. Screen ■ acrxy; 
w ■ OpenWlndwltriw) ; 
if (wa'NULL) goto quit; 
bitmzy ■ (atruct BitKap *> 

AllocHemlBlzeof (struct BltKap) .MEMF.CHIPt : 
if (bituyaaHULL) 
I 

print f ('No memory for xy bmap atruct. \n*) i 
goto quit ; 
I 

InltBltMaplbitmzy, DEPTH. WIDTH, HEIGHT) j 
for I l • 0; 1 < DEPTH; ;• • 
I 

bltatty->Planea[l] a 

IPLANEPTR) Al loc Raster (WIDTH. HEIG-HT); 

if lblt0iy->Planeati) a ■ NULL) 

I 

print f I'yz bitmap planes were null\n*l ; 

goto quit; 
I 
BltClear<bitmzy->planeB( il.planeaize.lt; 
) 

nevBcrzy.CuetomBitKap - bitmzy: 
scrzy ■ (struct Screen 'I 

OpenScreenltnewscrzy) % 
If leerzy.-NULLI 
I 

print f ('Unable to open screen ty.\n*ll 
goto quit; 



rpzy a aBcrzy->RaatPort; 

vpzy • lacrzy->ViewPort; 

LoadRG84lvpzy.catap.16) ; 

bitmxz ■ (atruct BltKap *) 

AllocKomtaizeof (struct BitHap) .KEKF.CHIP) ; 

it i bitmxz •■ NULL) 

1 

'No memory for xz bitmap struct . \n* ) i 
goto quit ; 
) 

InitBltKap(bltmXZ. DEPTH. WIDTH. HEIGHT); 
for (i-0; 1 < DEPTH; !••) 

I 

bitawz->Planea(l) ■ 

(PLANEPTRIAllocRaaterlWIDTH. HEIG-HT); 
It (bltmxx->PlaneaIil ■- NULL) 
1 

printf I'No 
goto quit : 



ry for xz bitmap planes. \n") ; 



for*v«i , ; 



) 

BltClear (bitmxz- -Planes [ i | . planeaize, 1 ) ; 

) 

nevscrxz.CuatomBitHap a bitmxz ; 

scrxz ■ (struct Screen •) 

OpcnScreeni&newscrxz) ; 
it (scrxz— HULL) 
{ 

printf ('Couldn't open screen xz.\n') ; 
goto quit ; 
I 

rpxz a l scrxz- >RaatPort ; 
vpxz ■ ■scrxz->Viewport : 
LoadRGB<(vpxz.caap. 16) ; 
xl - 0.0; 
yl - 0.0: 
Zl ■ 0.0; 
count a0 i 
count 3-0 i 
number*!; 
itoalnumber.atr); 
strcpy (out file, 'raau'ti 
atrcat (outflle.argvtl)); 
st rcat (outfi le. 'aet . ■ ) : 
atrcat (out file. at r); 
op« fopen(outflle.'W); 
tp a fopen(*ram:pointa". *w") j 

while! ( meaa-latruct IntuiHeaaage •) 

CetKsg(w->UaerPortl ) i-NULL) 
1 

claaa - m«sa->Clasa; 

code a awss->Code; 

RcplyHaglmeaa) ; 

If (claaa ■- CLOSEWINDOW) goto finish; 

if Kclaaaaa VANILLAKEYtfci(COde--'q')) 

goto quit; 
) 
f Pick a aet of specif lcationa at random. •/ 

r • randO % ntrana; 

coaza ■ coa(zalr) ) ; 

slnta a sin(zalr) ) ; 

cosxa * coa < xa I r I ) ; 

stnxa - sinlxalrl ) ; 

coaya ■ coa lya 1 r I ) ; 

sinya * ain(yalr) ) ; 

xo ■ xf Irl - xt (r] j 

yo - yf Irl . yt [r); 

zo « ztlrl • zt[r]i 

exf »xf |r]'(l-xa[r)l; 

cyf .yf [rl"ll-ya|r))j 

czf .zflrl-ll-zslrll; 

x • xl; 

y . yli 

z - zlj 
/• first scale V 

if <(xs[r]lli(ys(r)>l1(zs|r]l> 
I 
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XXS ■ X'KB[r] . CXfj 

yy B . y-y»!rl • cyf ; 
zzs ■ z"zs[rl • czf; 

X • XXS; 

y ■ yy«i 

Z ■ zzs; 



f* next translate •/ 

if((xtlr)HI(yt[rHli(ztIr)n 
I 

xxt • x . xt |rl; 

yyt . y . yt[rj; 

zzt ■ z . zt Ir] ; 

X ■ xxt; 

y ■ yyt; 

z ■ zzt; 
) 
/* then rotate V 
ii(ya) 
( 

zt ■ zo • Iz - xo)*coaya • (x-xo)*sinya; 

xr ■ xo . (x - xofcosya - (x-xo)-sinya; 

x ■ xr; 

i • xr; 
I 

lf(n] 
I 

xr - xo • (x - xol'cosza - (y-yoi •sinxs; 

yr - yo • (y - yofcosxa • Ix-XO) •slnxa; 

x • xr; 

y - yr; 
I 

iflxa) 
I 

ir ■ zo . (z - zot'eosxa - (y-yoj'smxa; 

yr • yo . (y - yo) -cosxa . (z-zo)'sinxa; 

y • yr: 

z • ir; 



) 



x2 . x: 
y2 - y; 
(2 . .; 

nextx - <LONGHxscele"x2 - xof fast); 

nexty » (LONG) <yscal*'y2 . yoffset); 

nextz ■ ILONG) (yscale*z2 • zof (set ) ; 

xl ■ x2i 

yl ■ y2; 

zl - z2; 

cc2 ■ Ir % 14) . i, 

SetAPenlrpxy.cc2); 

S*tAPenlrpzy.cc2); 

SetAPentrpxz,cc2> j 

If ( (n*xtx>0)t4.|nextx<640lfcMnexty>Olfcfcfn*xty<400)) 
( 

WritePlxellrpxy, nextx. nexty] ; 

) 

if I tnextz>OI*fc(nextz<64D)li4(nexty>OUt(nexty<400) I 
) 

WritePixoUrpxy, nextx, nexty); 

) 

ifUnextx>0>fct)nextx<640)H(nextx>0)fc4lnextz<400)) 
( 

nextx * 400 - next*; 
WrltePixellrpxx. nextx. nextx); 
I 

nextx - ILONC)x2: 
nexty ■ (LONG)y2; 
nextx - (LONG) 22; 
fprintf lop. * Id Id '.ec2. nextx! ; 
fprintf (op. ■ Id %d \n'. nexty, nextx) ; 
count2--; 

/• When output til* gets large close It and 
open another. •/ 
if <count2 > 12000) 



finish: 



fprintf lop,' Id Id Id Id \n*. dm. dm. dm. dm) ; 
fcloselop); 
count2-0: 
number-*; 
i toa (number. st r) i 
strcpyloutflle.'rem:*); 
street (out f lie. ergv[ll); 
street (out file, *set . *) ; 
strcatioutfile.stn t 
op« fopen(outfile.*w> • 

f Save the first SO points. If they do not 
plot on the Amiga screen we can-see where they 
are going and adjust scale and offsets. •/ 

count--; 

if (count < 501 

fprintf (tp.- Id id '.r. nextx); 

fprintf up,- Id Id \n', nexty, nextxli 

x2 ■ 0.0; 

y2 - 0,0; 

12 - 0.0; 

nextx * 0; 

nexty « 0; 

nextx • 0; 

goto forever; 

/* Save the three screens to ram: Do not 
forget to convert these to ILBM and copy then 
to a disk if you wish to keep them. •/ 
strcpy(outflle,*ram:*) : 
street lout file.argvll)>; 
strcaKoutfile.'xyii 
ofhxy »Openloutfile.HOOE_NEWFILEI j 
it I ofhxy la NULL! 
I 

for I 1.0; 1 < DEPTH; U.| 
( 

nb. Write(ofhxy.bitswy->PleneelU .planes. zel; 
i 

cols ■ fccraapIO}; 

nb- write (ofhxy. cols, colors lie) i 
Close (of hxy); 
I 

at rcpy (out Tile. 'rami •); 
street lout file. argvl 1J) j 
street (outfile.'zy* I: 
Ofhxy ■ Openloutfile.HOOEJJEWFILE); 
if tofhzy •- NULL) 
( 

for I l . 0; 1 < DEPTH; !••) 
( 

nb. Write (of hxy.bitmzy->Planes[il,planetlxe)j 
I 

cols - fccmap[0); 

nb- Wnteiofhzy, cols, colonize) ; 
Close (ofhxy! j 
) 

•trcpy (outf 1 le. 'rami ■ ) ; 
st rcat lout file, argv [l)t ; 
strcetloutfile.'xz'); 
ofhxz -Open(outflle,HODe_NEWFILE) : 
If (ofhxz !• NULL) 
I 

for ( l ■ 0: 1 < DEPTH; I**) 
( 

nb- write lofhxz.bi tmxz->Planes |1 J. planet ixe) ; 
> 

cols ■ acmaplO]; 

nb« Write(ofhxz.cols,coloreize)i 
Close(ofhxz); 
) 

if(op) 

( 

fprintf (op.* td Id td Id \n*. dm, dm. dm. do) ; 

f close (op); 



quit: 1 
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■ 
■ 

■ 

■ ■ ■ 






:•-.;■ • 






■ 

FreoMeafbi" 

II taerzyt Close 

I 

■ • 
width. ■ 



nesli) > 0) 
ry->pianes|i ) , 



ruct Br ' 



• of (struct BitMj( 
ltd of this run to the 



xol Esei i 



■ 
Free*<- 

tf (ucixji CloaeScreenla. 
- I'EPTH; ,-■ 

I 

■ 

FreeRaster (bitmxz->P]anea|l| . 
fclDTH. HEIGHT) i 

■ 

■ * 
ptn( a Ruft_NOtM". *a") ; 

. - 
• • - 

.«I.XOff««t(l 

fprintt lip,' %2. :■:•..• ■ 

■ 

: . - ■ 

fprintf Up.* 14. Of 14.01 

I .* l?.2f I 

■ 

- I 
vn'.xa 

t4.0f\n-.x 

■ 

.irtitent for Pun_Note»? 
. .noesocemlam" .\n*ij 



rpiipttup, • is ^n*. consent \ i 

felos*' 

CloseLlbrai -, ntMge) ; 

if (GfxBaac) 
Cc-flr> -baae) i 

• W) 

/■ itoa is from Kermghan ai 

itoalnt . 

char »•- : 



10 • 'Q'; 
10) > 0)j 



. 
da ( 
■tr|i**| - nr I 

■ 
if <slgn < 01 

' ■ ■ ■ 

[oi 

. 
■ CJ 



Listing 2 



KotaView - RMds ; >incs, 

plots x-y plane, rotates object about lines 
parallel with the x. y and z axis, saves a view. 
Copyright 1993 by Laura H. Morrison •/ 

■ include "stdi .' ■ 

.-.-.■ 

■ include "intui* ioi iin.h" 

■ include "intuition' intuit lonbese.h* 

■"c/exec.h* 
.le 'math.h* 
•define DEPTH 4L 

;iTM 640L 

■ HEIGHT 40QL 

•define MAXPOINTS 4000L 

U SHORT cnuipi I • i 0x000. OxfOO.QxQOf .OxOIC. 

OxffO.Ox.r: 

OxcOO.OxOur,. :*&*-*. cxccO. 
OxOccOxcOcOxcccOxT" 1; 
SHORT 'cols; 

■ • : ■ ■ 
struct Qtxaaaa •Olattaswi 
extern st rue - ■ 

extern »tru ■ 
extern acruci 
extern struct Bant for ■ 
extern struct Viewport 'vp: 
struct :.■:■■ 

0, C . ** . 

MKHEBI. 

■ 
•Screen * 
■ttuci 

0,0,640.400.0.1. 

■ CKSICLOSEHINDOWIVAHIU-AKKY. 
KINDOHCLOSEI ACTIVATE I BOfiDKP I 
SUPER_BITHAP. 
. \TTLL.NULL. MULL. 



■ 
struct 

■ 
static 
static 



CUSTCKSCREEN 
Window 'w; 
Rant Port "rp: 
Viewport *vp; 
BitKap "bitm; 
• 



■ -01 J 
int ccIHAXPOlWTSl 



h 
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■■ ■ 

■ ■ 
■ 

■ ■ 

■ 

■ 

■ ' 
MI n large, .■ 
.nt a: 

ULONGc: 

ushort 

b. g, nun 
I 

■ . 
lot. yof f«et, ;off»« i 
■fopand, "up. -pp. «ip. •op- 
color' 

i .Oi 
■ 

r,.. 

■ 



c potnt not 



•.V'l i 



• - 

• Hoed j 'ivpaT*»o' * 

ind of (nets \n'( i 

. . ■ ■ ■ 

' f ' f i x | ) 

(•cant (pp. • %i %i *,41ner». eh 

■ 

tscanf (pp.- M II - 

■ ■ ' ■ 

i . • i 
Oprr 

iryMt'lf 






■to rotate. \n\n'l ; 
■ ■ ' 

■ • " •*■ . 'b'.ot *g* to") i 

.' 'q' toquii. *n\n"J; 
oponfaigvlll.-; - 

mu.i 

: i 'Can't open object point-set. 

■ 

■ 

>-! , . * I 1 ' ■ *,tCCC,fcXX| J 

■ KAXPOINTS 

fclos-- 
goto rotate; 

ccc; 

I IO*t)XXj 

■ latliz; 
npoint.- ■ 

■ 
(ftr^ct !■ . * 



Qf XBase 



ry-.Oi; 



• 



■ 

QOt Oil' 

I 

■ «EW. HOT*: -opoint-Mt 
I" OBJECT vn\n*) ; 

■ 

■ Co| 

■ " 

■ 
. .. 

■ ■ 

■ 

■ ■ 



■ ■ ■ ■ 



' 



•HEIGHT; 

lap) .HEW_CHIP»i 



* t-<Mp structure. \n") : 
ntflbi 
I 

. L>EITH, WIDTH, HEIGHT) .- 
I • DEITH; 

IPLANEPTRI 

Al loctester (WIDTH. HEIGHT) 
-rlanestl) 
l 

•bitmapplanen were null \n* 
goto finish; 

BltCl««lbitiii->Plane»|i| . planes l;o. 1) ; 



— The complete Source Code and executable files 
may be found on the AC's TECH Disk 



Pleasewrite to: 

Laura Morrison 

c/o AC's TECH 

P.O. Box 2140 

Fall River, MA 02722 2140 
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Linking with HotLinks 



J>y Dan Weiss 



In the spring ol 'his year a new third parly extension to the 
Amiga (*S w.is introduced. It offers a powerful inter-process data 
exchange .m.l update mechanism Its .-ailed Hotl bth fhe tir-t 
products to use 1 1ml inks were PogeStnam, the desktop publisher, and 
two programs thai shipped with Hi>tl ink-. BM£ and Pasei titer BMI is 
a bitmap editor and Pagel incr is .1 formatted te>t processor. I ho next 
ionim.Tii.il programs to use HotLinks \m V from New 

Horizons and fmageMasfer from BUckBelt Systems, More commercial 
dei elopers arc Implemen tin g this standard, bul many de» elopers are 
unsure wh.it Hotl inks is. .md how to use it rhis article will help von 
both understand and Include HotLinks in your programs 

What Is HotLinks? 

I loll inks is the name for a system of programs, libraries, 
and data formats thai allow the MTtooth exi hange of data between 
programs on the Amiga The I loll inks system is made up <■( 

Hotl. ink- Iln resident code 

hotlfnks library I he shared Ubrarj 

several support programs 
To make I loll. inks complete requires one or more programs sharing 
data via Hotl Inks Hotl inks is isrt ARexx 

ol Select an edition... I Q 



fin 
fin 
Hn 
fin 
flr> 
ba 
ch 

& 

je 



iOock_DTPMorld u 
i Doc k_Manua i 
iDock_DTPWorld 
tgaLogic_Hrt ic le 
iga Logic w/Tags 

be 24 .brush 

eet ah . brush 

e. t iff 

agf ace . brush 

tLinks DTPMorld 

ss ica .brush 



/tags 



I 



A 



Cane 




Why HotLinks? 

There are many solutions to inter-process tile sharing. The 
simplest and most well-known 1% the standard i K Sk system Save the 
file in one program and open it in another. This is the universal system 
that ships with all Anngas I lotl inks use the Standard v>S .is .1 nunlel 
with two important extensions: updates an. I consistent tile formats. 



I pdatesin Hotl inks cn.ible any number of programs to keep up with 
the current status ol any Rte th.n they are linked loo. This means thai 
.is soon as .1 change 1- made In one program, the change can he 

reflected 1" Several other pfOgramS WlthOUl any user intervention 

( onsistent Me formats is the logical application of IFF rhv distinction 
is that not only do the formats meet the needs of .ill users, hut all users 
use the ■»»"<* format Proprietary formats are great Em s,n ing program- 
specific formats in program-specific manners, but a good interchange 
can be used by many programs. Furthermore, all Hotl inks programs 
us*' only the agreed-on formats when publishing to Hotl. inks, assuring 
that each data type is passed 111 only one w.n Notification and 
consistenl hie formats give HotLinks its R|ust WOrksSeafleol use, and 
makes it usable by even the most novice of users 

How Docs It Work? 

Average Hotl ink- user- place I lot! ink-- 111 their VVBStartup 
drawer I his way it is always ready to facilitate data-sharing When a 
program wants to access the I loll inks system, it list's the shared 
library to message the resident program I he resident program also 
makes sure that when a tile is updated, aru subscrib in g program is 
notified, even if it is not running at the tune through the shared 
library the program can create standard data structures lor handling 
Publu.it ion {Hotl mked tiles) Information I ring the library calls to 
create and handle these dab structures insures compatibility even if 
the structures change signlficanUy in the future The library also 
serves the important function of insulating the programmer Irom the 
Kdois n and dlrtyS details ot how the file is exchanged, In this w.n 
mas-ive changes and improvements can be made in Hotl. inks without 
breaking any programs. The important thing to remember is that 
Hotl inks is designed not |ust tor today, but for today and tomorrow 

Links In a Chain 

So. one programmer to another, how din's it work' Here is .1 
Call-level explanation ol a HotLinks exchange, first let's publish a 
document RfSt we try to open the shared library; if the HotLinks 
resident program is not tunning .the lihrarv won t open and we stop 
i' re Wter we get the library open we use the first Hotl. inks. all 
III Register to register ourselves with the Moll inks resident program 

■ 
• 

lll.Register asks the calling program to supply I tour -haraetcr ID (or 
■ts,-it. .1 message port for notify messages, and 1 screen pointer so thai 



7? 



AC'S TECH 



What is HotLinks? 
Why HotLinks? 
How Does it Work? 



Hoi Links can open Its requesters on the proper ween Hi Register 
returns a handle that is used In subsequent cabs to identifx the calling 
program. This call, m effect, lets l lotlinks know who you are and how 
to get your attention 

Next we need to create a Publication Block A Publication 
Block.orpbhvk.isii ,, kmmn. ts the standard data structure used for 
passing Hoil.inks-nAitt.-d InfornutkHi around Instead ol having lo 
change your code every time then- is a change m die pblock structure, 
we call AllocPBIock to create an empty pblock tor us 

■ " 
We pass our l loll inks handle and a receive, a pointer lo the pblock. 

In this example we are looking to Subscribe loan existing 
1 lot! Inks Edition so we need to call CietPub lo open the standard 
HotLinks edition requester. 

• - 

The HotUnks edition requesta looks like a standard file requester, but 

isn't suite Hull ink- deals only with its own tiles. GetPub needs tile 
newly created pblock and a pointer to a simple Miter procedure. Since 
there are several different kinds of HotLinks editions, a filter proce- 
dure is used so thai the user b) gh en i choice «>r only those hies that 
would work with .1 given program The filter procedure t> pkally looks 
al the type in the editions pblock to determine U is .111 edition that 
should be listed In therequestet \ good example of a simple filter 
proc is included in mi example program in the I loll. inks developer kit 

When theusci has made his choke, GetPub will return with the pblock 
lull of information about the edition. At this point HotLinks and the 
standard tile system begin to look alike 

It we want to modify the data in any way We muft get I 
Write lock, Thfc) prevents anyone from getting permission to modify 
the data while we mav be modifying it Irtfl is >er\ Important since 
the bask assumption of HotLinks is that more than one program will 
be accessing the Same data al the same tune lo gel .1 wnte lock, we 

need to call LockPub. 

■ 

I OCkPub takes the editions pblock M\A some (lags (hat indicate it we 
want a read lock or write lock, or we want 10 unlock a locked file It is 



important to note thai HotUnks locks are RsoftS Dug means that if the 
machine is rebooted, then all locks are lost rhis is fine since no 

pr.igram should be able to permanently hold a lock on mi edition 

After obtaining a write lock, the pblock is passed totheOpenPubcaU 
to gain access to the edition 

;>enPub( struct PubBlock "pblock, int 
flags! 

Now that w.u have both lite tile and a lock on H. you can access and 
modify it as you see fit using tlwKeadPub, WritePub.andSeekPub 

calls 

■idPubtstruct PubBlock •pblock, char 
.onl 

-. 'pblock, char 

"but!' 

PubBlock 'pblock. 
ags) 

lor the most part these work like standard OS calfs 



H Nwit A De-sc . | 




_0K _ I 



Cancet| 



Ihe trick now is what to read and write 1 lot I inks files are 
vcrj similar to theii IFF counterparts, usually with a few minor 
extensions iv bitmap formal has spe- ,ii, e x tensio n s to the BMHD 
chunk defining what type of picture that data represents— Palette, 
Gmyscalc,rrcB,RCrM.CMYK t CMYKA— end the resolution of the 
image I he text format DTXT, is 1 completely new HI- format. The 
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reason lor this is th.it it rocs well beyond ASCII to pro*. Ide complex 
text formatting th.it professional word processors need. But .is you will 
see in tin' example programs, it tan also he simple enough for basic 
text use. The really important thing to note here is thai there is only 
one text format and only one bitmap format, not 10 of each. This 
means once you support Hot Links text files you never have to wnte 
another chunk of code to support text via HotLinks 

After Mi edition has been modified you will want to publish 
the changes. This is called updating. To update a file. limply write out 
a new version of the edition and close it with CloscPub. 

lot rrioi • CloaaPublairuci PuMlocK *pblock> 

This lets HotLinks know that this is a new version of the edition. All 
files that have notify set for this edition will be notified ot the change 
in version. 

Since you have accessed the file, you may also want to be 
notified of any further changes by other users. The Notify call is used 
to set up a link between HotLinks and the calling program concerning 
a given edition 



When you are publishing a new edition to Hotl ink-., the 
sequence is much the same First you register with I H. Register if you 
are not already registered, allivate a pblock With Alloc Pit lock and then 
call PutPub. 

■ 

PutPub presents the standard HotLinks requester tor publishing a new 
edition. It allows the us« to name the edition as well as set certain 
RCUrity information I'utl'uh accepts the standard pblock and will 
display the NUne. Description, and Access information it it is present 
riiis is the proper wa\ to Suggest default values to the user I he 
fillerproc parameter is not used at this tune 

Once PutPub has filled in the pblock you can set up a 
standard notify with Notify, get a write lode with LockPub, and access 
the lile as you did in the example above with OivnPub, Writel'ub, 
SeekPub and ClosePub. Be sure to always get a write lock when 
modifying an edition. Finally, when you are done, cancel the notify 
and free the pblock. When you are done with HotLinks, exit cleanly 
using the UnRegister call. 



ir.i Bitoi • Motityiitiuct PuMlocX •pOtock 

■UMrdMfll 

Notify takes the pblock for the edition you want the notify message 
for, along with a flag that indicates if you are setting up the notify, 
canceling the notify, or setting up an exclusive notify The notify 
message itself will be sent to the message port that was spo u'ted in the 
HLRegistercall. The message will bean HI.Msg struct. 

Normally it is simplest to set up a notify on an edition when 
you first start using it and remove it when you are finally tinished with 
the edition Doing this means you will receive a notify message for the 
changes you make as well as those made by other programs. To 
prevent rereading an edition you have modified, use the PubStatus call 
to see if the current edition is different from the one you have 

Int viror • PubStatuaiai tuci PubfitocX "pblock) 

PubStatus will return the status of the edition specified by the pblock. 
in the return error. 

When you are finally done working with an edition, you 
need to cancel the notify and free the pblock. You cancel the notify 
with another call to Notify. To free the pblock, call FreePBlock. 

int after • n««raiochiatruct Put* lock -pblocki 

It is important use the FreePBlock call since the pblock may likely 
change size in the future. Remember each notify should be cleared and 
each pblock should be freed before finally leaving HotLinks. 

To leave HotLinks, you must make one last call. UnRegister 

lnt error • Ur-RafliataMUUWQ handlai 

UnRegister frees the handle allocated by HLRegister and lets I lotl inks 
know that the calling program is no longer connected with the 
HotLinks system 



Other Calk 

A simple look at the HotLinks documentation will show 
several calls that have not been discussed. These fall into two catego- 
ries. The first is user access management. Set User sets the current user 
of the HotLinks system, Generally this is not necessary as the users are 
already logged in. Use of this call is best left to the login process. 
\ewPasswordand ChgPassword also fall into this category, and again 
are best left to HotLinks support programs. 

The other category of HotLinks could be called Rbehind the 
scenesS For the most part you will not need to use these calls, but ) OU 
can if you need to get a little deeper into Hotl inks RemovePub deletes 
an edition if the user has access to do so This is used mostly BS ■ 
cleanup measure when edition can not he properly completed. 
I irstl'uh gets the hrst edition that is available Note that it does not use 
a filter proc so this may give you a pblock to any edition NextPub. and 
successive calls to NextPub, will give you a pModt H the next edition 
in line. These two calls allow you to search the entire set of editions. 
Getinfowill fill in a pblock that has the i.d of an edition set in it This 
is how you can get a lull pblock without forcing the user to reselect the 
edition via CietPub. It is suggested that when you save a file with a 
HotLinks edition in it, you store the i.d .and version number from the 
pblock as well as the actual data. Storing the i d and version number 
only forces you to use Getlnfo and have an up-to-date pblock. Setlnfo 
changes an editions pblock to match the supplied pblock. Be sure to 
call Getlnfo first to till the pblock so that information you do not 
change will be maintained. Finally Publnfo allows the user to update 
or change the information associated with an edition. The Publnfo 
requester is the same as the PutPub requester 

Real World Example 

Now that we have run through a logical example, lets run 
through an actual program. The program is called text2hl Ihe 
complete code for this program along with code for several other 
Hotl inks programs is m.luded with the Hotl inks developer kil 
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• . ••c.n. 

■ inp1udvpro(o'dom.h> 
tinclud* «*»'!»©■. h. 

■loeludi 

LnkaJu 



I 
■ 



■ 

■ 



■ 

■ 



■ 



' * v»i iion [. : 

VttSTI 30.91f< 



ud. daclara' 



chat- ■•! 



DMtMl 

unaignod lr.t chunkiypai 

■ 

■ 



The first thins the program does is to try to open the 
hot links, library. If HolLinks is not running, the library cannot be 
opened and you should give up right here. 



hatllnai ■■ : 



I hi th» 



After opening the lihr.irv. jrou need to register with Hot I inks 



II SI is passed as the signature for this example, and mihviI will mil 
be receiving any msgs. NULL (0) is passed fw the MsgPori parameter 
Tlie program is running on the workbench so NULL (0) is pas' 
the screen parameter. 

AllocPBIock is used next to create a pblock that will be used 
to publish the new edition. It is important to check the pblock to moke 
sure that is was allocated, and did not return an error 1 or now the 
Hotl inks side is ready We need to check the fDe size of, and open the 
text tile thai is to be published. 



■ 

■ 



'. -■ 



INOMtVI I 



•IIOI.I 



■ 
■ 



■ 



■ 

:_»EA-->li 






: I TJtPoH ■ 
thutdowniu 

■ 

•bwok - eo 

Unlock 

/■ opt- 



' - Id ■ . 

•hotdnntli 
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Once the source text die is open, stuff the pblock with 
Type. Access, and Name Information, and call PutPub. PulPub 
presents the PutPub requester and allows the user to change any of 
the information. PutPub then updates the pblock so that all 
information is current. Again make sure that PutPub returns 
NOERROR before continuing. Open the publication for wilting 
using the new pblock. If you are able to do this, it in effect gives 
you a write lock on the file, so no call to LockPub is needed. No 
actual lock is set, but HotLinks will not allow any program to gain a 
write lock when an edition is open for writing. 

/• ■•( up mm d«(aulta •/ 
pb->PRee.Type ■ BWTi 
pb->PRac.Mcaaa - *cc_MfAULTi 
atcgfn(pb->PRec.MaM, argvllli, 

'• gat a publication ualng tha publication raqueiter 
provided by the 

• hotllnk. library. 
•/ 
•rror • PutPubipb. Oil 



/• 11 tha uaar selected a file ar-d praaaad o* tban dalata 



the (!;■•' 



if larrori.NOBttoai 

I 



/• check for error* •! 
avltcrilarrori 



violationvfl'l i 



parameter* \n" i i 



caaeNOPRlVt prlntf i-ERROR; privilege 

break; 
caaa IWVPARWO prlntf I'DOOfli Invalid 

bcMki 



Cioaaifiii 
anutdownu i 
•*»lO»t 



At this point we are simply writing out a normal IFF file 
to HotLinks using WritePub call. If for some reason the process fails 
before the edition is fully created, it is important to delete the 
edition with RemovePub, as il is an invalid edition. 

/■ opan tha publication flla •' 
ifllerror-OpenPublpb. 0PEN_WR:TC1 > i.HOEMORl 



for wrliingVft* 



prlntfCERROR - could not opan tha publication 

ClOMIIllI 

ahutdrnmm 
a»lt(fln 



ehur.ktypa . FORWi 

WritaPublpb, Ichar *)fcchunktype. Ill '* wrlta tha FORM tag 
* 

enunkaUe - fiL*ait«*12i 

WritaPublpb. ichar •ifcchunkaire. II j /• -rite tha rORH alia 
■ 

chunk type • DTXTi 

WritaPublpb. Ichar •Uchunktype. 41, /• write tha rORM type 

WritaPublpb. (char ' uchunktype. 41 i /* write out the chunk 
header iDTXTi •/ 

chunkaite - filestie; 

WritaPublpb. Ichar *)fcchunkaize. 41 i 

'• allocate ceaory to hold tha chunk •/ 
ifHbuff-*.llocMa»lflleaue. on. .01 
l 

prmti i* error - out of ■a-ory'n'ii 

CloaaPublpbi i 

ClOMlllll 

RaauvaPubipbi i 

■hutdovnili 

exit 10) i 



I 



'* read tha chunk data in *' 
Keadlfl. buff, rilaalial; 



nevien • xr Itataxt <pb, buff, f Ileal rei ; 



'• pad tha flla out to an avan byte *l 
1 1 1 1 1 lM I lafcQMQQQDKOL I 



•buff - 0i 
writaPublpb. buff. 111 



'• traa tha «a«ory uaed */ 
FreeMemlbuff, flleeiiel, 



'• cloea tha input file •! 

ClOMltlti 

/* adjuat tha chunk langtha for tha coaaMnda written out •' 

SeekPubipb. 4. SEER_BIOINmw0 > ; 

chunks lie • newlen«13i 

WritaPublpb. ichar • Jicrtunkswe. 41; 

SaakPubtpb, S. SEEx_currf.mtj , 

efauokalu • newletw 

WritaPublpb, ichar "l.chunkelie. 41 1 

SeekPublpb, 0. SRIR.OID): 



Since the edition is in DTXT format, we need to use the 
routine wrttetext to publish the DTXT version of the source text file. 
As you can see, this is a pretty straightforward process since only the 
tab and newline characters need to be translated for the DTXT file. 
The translation takes the form of creating DTXT tags for each 
command to replace the single character code. Writetext returns the 
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actual length of the DTXT data written since labs and newlino tags will 
cause the data to expand. 



IK Hi . rotwulpb. buff. l*nl 

■tract PuMLock *pbj 

char -buffi 

mi l*ni I 

I 

IK flmi 

chai contend, etlao. clni 

flrn . B| 
whil*u«ni 



.. . • ■ • ■ 



'• irtlt* out th* TOT.T*B conund •/ 
CAB* 0x09i coMand . TtXT.TABi 

cflag • TOT_nJkGS_TABi 
clan • 0i 

WfltaPubtpb. ic:-r 
MruvPublpb. fcco—and, in 
Writapubtpb. trtlag. ;i; 
"rit*Publpb. IclM, 1U 

br**k. 

'* writ* out th* TSXr_NEVLlNE cocMnd */ 
e«a* OxOar coapand - TUr_NEHLIHt< 

cflag . TEXT_rLAC5_NEWLINXi 

cl*n ■ 0; 

HTitaPublpb, kin, 1|| 

KrttaPubipb. tco-Mnd. 1); 

wmePublpb. kcflag. til 

WrltaPublpb. tclan. Hi 

flan.. 4 j 

break i 

'* writ* out th* taxi ttaalf •/ 
default: WrLt*ft,bipb. butf. lh 

flat... j 

tuMti 



I 

lM-1 

buft..; 



muni (i*oli 



When the edition is finished, ot if the program aborts, there 
is still some cleanup that must take place. This is contained in the 
shutdown procedure. First free the pblock with FreePBlock, then 
unlink from Hot Links via UnRegister. Finally close the library with the 
standard DOS call. 



/• cloaa th* publication •/ 
CloaaPublpbli 



irmtoQwnO; 



void ahutitownu 
I 

itlpfal 



ifihlhi 
I 



• fraa th* publication block polntat •/ 
Fr**raiocalpb)i 



'• unr*oiat*r thla prograa f ron hotl in** •/ 
IMaelBMcfUMl 



I 

if (HotLinkaB^Mi 



'• ClOl* tha library •/ 
ClcaaUbraryHatruet Library -iHotLinkaBaa*) , 



Final Notes 

There you have it. Not too hard is it? While I was writing 
this article, I was struck with just how easy it is to implement 
HotLinks. The documentation can be a little scary, but in practice it is 
no different than reading and writing normal files. If your program 
already reads or writes IFF 1LBM files, then you are inches away from 
exchanging files with PageStream, BME, and ImageMaster. Even 
better, the more programs that support HotLinks, the more programs 
you'll work with. HotLinks is pretty exciting, and it will be getting 
even more exciting in the future. Remember, though, that only a 
program that follows the rules gets to keep up with the fun. Be sure to 
get write locks! 
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Charge my Visa 
Expiration Oaie . 



MC • 
__ Signature 



VISA 



Please circle to -nOcafe this is a New Subscription u I Renewal 




US $27.00 
Canada/Mexico $34.00 
Foreign Surface S44.00 



US S37.00 
Canada/Mexico S54.00 

Foreign Surface $6-1.00 



4 big Issues! 
The ONLY Amiga technical magazine' 



US $43.95 
Canada/Mexico $47.95 
Foreign Surface $51.95 



Please call tor all other Canada/MexIco/torelgn surface & AH Mall rates. 
Check or money order payments mutt be In US lunda drawn on a US bank; subjeel to applicable sales lax. 




High 

Resolution 

Output 

from your AMIGA™ 
DTP & Graphic 
Documents 



You've created the perfect piece, now you're looking for a good sen-ice bureau for output. You want 
quality, but it must be economical. Finally, and most important... you have to find a service bureau thai 
recognizes your AMIGA file formats. Your search is over. Give us a call ! 

We'll imageset your AMIGA graphic Hies to RC User Paper or Film at 2400 dpi (up to 154 Ipi) at a 
extremely competitive cost. Also a\ ailable at competitive cost are quality Dupont ChromaCheek ' 
color proofs of your color separations/films. We provide a variety of pre-press sen ices for the desktop 

publisher. 

Who are we? We are a division of PiM Publications, the publisher of Amazing Computing for the 
Commodore AMIGA. We have a staff that really knows the AMIGA as well as the rigid mechanical 
requirements of printers/publishers. We're a perfect choice for AMIGA DTP ttnageseiting/prc-press 
services 



We support nearly every AMIGA graphic & DTP formal as well as most Macintosh™ graphic/DTP 
formats. 

For specific format information, please call. 



For more information call 1-800-345-3360 

Jus i the \cr\n e b 



TM 




Finally! True Cinematic Quality Morphing For The Amiga ! 





ASDG is not ihe first to advertise 
"cinematic quality morphing' for the 
Commodore Amiga*. I laving seen 
the other products, there?, obviously 
rm re than one way to define thai 
term. 

lo us, "cinematic cjuality morphing" 

means these things: 

• Morphing must be fast. 

In a production environment, time is 

mi mey. ASDG's MorphPlus is the 

fastest morphing pre jduct available 

lor the Commcxiore Arnica 

MorphPlus powers through 

complicated iull overscan morphs 3 
to 1 1 times faster than the other 
products. 



Fastest MorphPlus" 

a-To-Use MorphPlus"' 

Highest Qualit) MorphPlus 



• Morphing must be easy. 

Experts in I he held praise the 
intuitive design of the MorphPlus 
user interface which leLs them create 
sophisticated full motion morphs in 
minutes instead of weeks. 

•Morphing must be high quality 
im i that it truly can be used for 
cinematic or professional video 
applii ations). MorphPlus" is already 
in use in Hollywood productions. 
replacing high end systems. 



I his is what we mean by "cinematic 
quality morphing.' 

If these .ire the criteria you would 
use, then MorphPlus' is the choice 

you should make. 

See it at your local dealer! 




925 Stewart Street Madison, Wt 5371 J 
608/273-6585 



Whafs 

JS? 



EEHE 



More! 



•K mm**, an tncfemarittd i* thu ir» b< .liwl 1 1 imp.ww.-* MivphPlua -vsix , Iiki-ixwjimI 
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